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1.0 INTRODUCTION 


This document is intended to provide the application programmer 
the necessary information and reference material to write 
application programs for the NABU personal computer. Complete 
programming information on the internal operating software (IOS) 
as well as programming information of the Video display processor 
and the programmable sound generator are included. 


One of the aims of this manual was to collect all the information 
that was previously found in several documents into just one. 
Although this has yielded a document of some 200 pages, each 
section discusses a single concept related to the programming 
environment at NABU. Therefore the programmer need only 
investigate the portions of interest and not have to read the 
entire manual. 


In order to put the IOS into perspective, we include here a 
section from the IOS Specification which spells out the 
general functional requirements of IOS. This will enable you to 
judge what to expect from the Internal Operating System. 


DESIGN REQUIREMENTS 
Overview 


This design specification defines the Internal Operating 
Software (IOS) for the NABU Personal Computer (NPC), a low- 
cost, expandable personal computer. It is unique because it 
is capable of communicating on one-way, hybrid and two-way 
cable systems and telephone networks, as well as operating in 
a stand~alone mode, depending on which options are selected. 
When used in association with a CATV network the NABU P.C.'s 
prime function is to run software downline loaded from the 
cable head-end. 


A versatile set of internal operating system and device 
handling software is required for the NABU P.C. to run appli- 
cations software under control of a user. For definition and 
development purposes this software, collectively referred to 
as the Internal Operating Software (IOS) consists of: 


Applications program interfaces to IOS facilities 

All physical device control and I/O handlers 

Basic task controlling and interrupt handling software 
Communications Software 


9000 
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The internal operating software does NOT include: 


o Human Interface for Selection of Applications Programs 

Any ROM Software in the NPC 

o Programming languages (eg. BASIC is not part of the 
operating system.) 

© Monitors (ie. examine and change memory, etc., etc. ,etc) 

o High-level (user oriented) utilities 


° 


Operating Environment 


The IOS must interact with four other functional components 
of the NABU P.C.. These are: 


o The Basic NABU P.C. hardware 

Optional hardware and peripheral devices 

o Communications with external systems, 
including the keyboard and NABU Adaptor (NA) 

o Applications Software 


fe} 


It is the requirements and functions of these components 
which essentially define the requirements for the IOS. 


Internal Operating Software Requirements 


The fundamental requirement of the Internal Operating 
Software is to create an environment which supports the 
loading and execution of applications programs in a_ simple, 
efficient manner. The NPC hardware, its peripherals, communi- 
cations and the IOS are really just necessary evils required 
to present content to an NPC user. The IOS provides a stable 
interface which allows applications access to the other NPC 
components while hiding the messy details of the hardware 
configuration and communications protocols, which are really 
of no interest to applications programs. 


‘IOS Flexibility 


In order to be as flexible as possible, the IOS resides 
completely in RAM. A separate program, the MAIN MENU pro-~ 
gram, is loaded in along with the IOS when the NABU P.C. is 
"booted". The MAIN MENU performs all human interface func— 
tions required to load in an application. 
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A number of expansion options will be offered for the NPC. 
These options may include: standalone operation through use 
of ROM readers and/or floppy disks, additional communications 
options though the use of telephone dialers, two-way cable 
modems and other devices, and the support of various other 
peripherals via an I/O expansion bus. The IOS must be able 
to operate in a configuration independent manner. This 
implies: 


o The IOS must be able to sense the NPC configuration when 
"Booted" 

o The IOS should protect the applications from becoming 
"configuration-dependent" 

o Standard I/O handling procedures and I/O routing must be 
included in the I0S 

o The IOS may be required to operate using different types 
of primary storage devices. 


Applications Interfacing 


As was mentioned earlier the NPC and IOS exist to run appli- 
cations. In this sense applications software is the highest 
level of software and it is in control of the IOS. Different 
applications have different requirements. Animated video 
games and other applications which require rich active human 
interfaces will require fast, efficient, unadorned access to 
NPC devices. At the other end of the scale are many of the 
computation type applications which are willing to sacrifice 
speed for I/0 independence and ease of use. Other software 
such as a screen~oriented word processor lies between the two 
extremes of support. 


This implies: 


o Applications must have as much control as possible over 
the I0S 

o Applications should be able to access IOS features at a 
number of different levels 

o IOS support should be designed to fit applications 
requirements and not vice versa 


Real Time Requirements 


Unlike many other microcomputer operating environments, the 
NPC will have time-critical tasks. The most obvious of these 
is communications on the CATV network. However many of the 
applications planned for the NPC have real-time components. 
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This implies: 


© The lower layers of the IOS must be as time-efficient as 
possible 

o Interrupts must be well supported in the IOS 

o Applications software has as much control as possible over 
the enabling of interrupts and the complexity of interrupt 
handling 

o Some simple tasking constructs should be provided 

o Attachment of applications supplied code to interrupt 
handlers should be supported where possible 

oO Real-time counters (60Hz rate) should be supported by the 
Ios 


Application Time-out Requirement 


Due to the T.V. screen being used for the basic output dev- 
ice, if no keyboard input is received for long periods of 


time (approx. 20 to 30 minutes), the T.V. screen will go 
blank (to prevent burning of the TV screen). This assumes 
that the clock interrupt is running, inorder to do the tim- 
ing. The program execution must continue even though no-= 


thing is being displayed. When any key on the keyboard is 
activated, the T.V. screen will return back to its normal 
display. The keystroke which re-activates the screen is not 

passed on to the application program. {This time-out will 
also be active if the NPC is in the "PAUSED" mode.} fhe enty 
exception to time-out requirement ts the ease where the 
NevPvE€> t¢8 tn a Zhait™ mode beeause the PAUSH key has been 
activated: The PAUSE funetion enuses the FOS te execute tn a 
very tight jeep, untii PAUSE funettion +s deretivated: Phis 
tight teep seans the keyboard fer the netivatien ef the 
PAUSE, PV‘NABU; and S¥M keys: 


Size Requirements 


The total size of the IOS Kernel should not exceed 10K bytes 
and shall be kept to a minimun. In order to accommodate all 
the different IOS functions, the IOS will be divided into two 
sections. The first section will be called the Kernel. This 
will form a "bare bones" type IOS. The remainder of the IOS 
will form the second section which is called the Extended I0S 
(XI0OS). As applications require functions which are only 
found in the XIOS, the application will be able to load in 
the necessary sections (modules) of the XIOS, and then use 
the functions. When the functions are no longer necessary, 
the XIOS module can be deleted, thus freeing up memory space. 
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Internal Operating Software Structure 


The Internal Operating Software is divided into three 
functionally separate components. These components are: the 
I/O handlers, the Basic Operating Software (BOS), and the 
Downloadable Operating Software (DOS). 


I/O Handlers 


These portions of the software contain the low-level control- 
ling code to handle input and output devices. Each physical 
device has its own I/O handler. This software masks’ the 
detailed physical operation of peripheral devices so that the 
higher levels of the operating system may be peripheral 
device independent. I/O Handlers provide: 


Hardware Dependent Device Control Code 
Interrupt Handling 

Initialization Code 

Data Link Layer Communications Protocols 


ooo°o 


Basic Operating Software (BOS) 


This level of the operating system provides the key operating 
control software for the NABU P.C.. It interfaces to the I/0 
handlers, the Downloadable Operating Software and applica- 
tions programs. The BOS provides: 


Functional Level I/O handling 

Calling of I/O handlers and device control code 
Interrupt and task handling control 

A Method of Linking Directly to each BOS Routine 


oo0°0 


Downloadable Operating Software 


This is the highest layer of the internal operating software. 
It interfaces to the BOS and applications programs to 
provide: 


o Common Entry Points for Applications 
o I/O Routing 
o Configuration Identification 
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2.0 THE NABU NETWORK 


The NABU Network was formed on the idea of linking a 
microcomputer to the cable network. The union of these two 
technologies has paved the way for the introduction of a 
microcomputer complete with a large base of software into the 
homes of the population at large. 


This section will describe the various links in the chain of 
this Network with a view to giving a broad understanding of the 
pathway followed by an application program from the cable company 
to the end user's RAM. Refer to the diagram for a pictorial 
representation of this data flow. 


The Head End 


As the name suggests, this is the originating node in the 
Network. The Head End is actually a minicomputer and it is here 
that all the programs and data to be broadcast on the cable are 
found. The Head End minicomputer is constantly outputing the 
information in its database and it does so in a cyclic fashion - 
when all the information has been sent, the mini starts at the 
beginning and re-sends the database. This cyclic nature of the 
data flow enables one to envision the data as being written on 
the edge of a wheel which is read as it revolves. 


Each application on the “wheel” is tagged with an 
identification number. This number becomes important at the 
other end of the NABU Network to select the proper user applica- 
tion. 


The Head End is also responsible for the maintenance of this 
database. Any additions or deletions must be carefully dealt 
with in order to ensure the overall integrity of the information 
as these changes will alter the "diameter" of the "wheel". 


The RF Modulator 


The information output by the Head End mini is of course 
digital in nature. Before this can be put onto the cable, the 
data signal must be modulated. The RF modulator will perform 
this function. 
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The Combiner 


Since there are other services on the cable (eg. TV, radio), 
there must be another piece of equipment that will merge the NABU 
programs with that information. The Combiner performs this task. 
The NABU information is now broadcast on a specific channel and 
sent into the cable for distribution. 


The Adaptor 


The Adaptor is a piece of hardware that acts as the interface 
between the cable coming into the home of the NABU user and the 
NABU Personal Computer. 


Essentially, the Adaptor performs the reverse functions of the 
Combiner and the RF Modulator. It is tuned to listen to the NABU 
channel, de-modulate the signal and convert it into the digital 
data that the NABU PC can understand. 


On the cable side, the Adaptor is only capable of listening to 
the information coming down the cable - it cannot send commands 
back to the Head End. However, on the PC side of the Adaptor 
there is two-way communication. The PC can tell the Adaptor what 
it wishes from the cable and the Adaptor can inform the PC when 
that data is available to be read. 


Thus, when the user requests a particular application, the PC 
sends a Read command andthe identification number of the 
application to the Adaptor. The Adaptor then "listens" to the 
cable until the appropriately identified data appears. The 
Adaptor fills its internal buffer and then informs the PC that 
the data is ready. The PC obtains the data from the Adaptor 
putting it into the appropriate location in the RAM of the PC. 
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3.0 THE NABU PERSONAL COMPUTER 


INTRODUCTION 

This section will provide the application programmer the 
necessary introduction and information to the hardware of the 
NABU Personal Computer. 

3.1 MEMORY ORGANIZATION 


The NABU Personal Computer is a 80 Kbyte machine. The 80K is 
partitioned as follows: 


1) The primary memory is 64K in size. It is the only region 
where 280 microprocessor code may be executed. 


2) A 16K block of memory is dedicated for use by the TMS 
9918A video display processor. 


| | | 

1 | | 16k videol 
| | I RAM | 
{ 64K RAM | ! | 
I NS 
I I . 

| ! . 

| I . 

| Z80A | ITMS 9918A] 


The above figure graphically describes the memory 
organization. 


Spec. 50-90020490 Page 1 - 9 June 8, 1984 


VIDEO DISPLAY PROCESSOR 


3.2 THE TMS 9918A VIDEO DISPLAY PROCESSOR 


Spec. 


The TMS 9918A Video Display Processor (VDP) is responsible 
for all video display for the NABU Personal Computer (NPC). 
It provides for text, graphics and animation. Detailed 
knowledge of the control of the VDP is not required since 
all functions of the VDP are accessed through routines 
provided in the Internal Operating System (IOS) of the NPC. 
This section will outline the features of the VDP and the 
use of IOS routines to generate T.V. images for display on 
the NPC. Further information may be found in the Texas 
Instruments 9900 Data Manual (TMS9918A/TMS9928A/ TMS9929A 
Video Display Processors). 


The VDP produces a T.V. image that can be envisioned as a 
series of display planes. Each plane has a display priority. 
An image ona plane of higher priority will overwrite an 
overlapping image on a lower priority plane. The display 
planes in order of lowest to highest priority are BACKDROP, 
PATTERN, and SPRITE. Sprites are special animation objects. 
The VDP provides 32 sprite planes, with sprite plane 1 
having the highest priority. 


The lowest priority plane is the BACKDROP, which consists 
of a single colour. It can be set to any one of 15 colours. 
The area covered by the backdrop plane is larger that the 
other planes, and can form a border for the pattern plane. 
With the T1.V. displays commonly used with the NPC, the 
border effect is generally limited to the top and bottom of 
the screen, while the side borders are cropped by the T.V. 
overscan. The colour of the backdrop is determined by write~ 
only register 7 of the VDP (see 3.2.1 REGISTERS). 


The image displayed in the pattern plane is determined by 
the contents of 16K of Video RAM (VRAM) provided for the 
VDP. The contents of the PATTERN NAME TABLE (Name Table), 
PATTERN GENERATOR TABLE (Pattern Table), and COLOUR TABLE 
allocated in VRAM define the pattern plane image. The mode 
of the VDP determines the size and organization of the 
tables and hence the way in which VRAM is mapped to the 
screen. The VDP can operate in any one of four modes, Text, 
Graphics I, Graphics II, and Multicolour. 


The images displayed in the sprite planes are defined in the 
SPRITE ATTRIBUTE TABLE and SPRITE PATTERN GENERATOR TABLE. 
These tables are also allocated in VRAM, and perform the 
sprite equivalents of pattern plane tables. 
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The VDP produces a screen image with an absolute resolution 
of 256 X 192 pixels. The VDP divides the pattern plane into 
blocks of pixels called patterns. In Text mode, the patterns 
are 6 xX 8 pixels, yielding 40 text pattern per line. In 
Graphics modes the patterns are 8 X 8 pixels (32 patterns 
per line). There is a one byte entry in the Name Table for 
each pattern position on the screen. For example, in 
Graphics modes, the Name Table is 768 bytes long (32 
patterns per row X 24 rows of patterns). In Text mode, the 
Name Table is 960 bytes long (40 X 24). There is a one-to- 
one mapping of entries in the Name Table and screen pattern 
positions (see Figure 1 for example). The screen origin is 
defined as the top left corner. 


teocte--t - - - ee teentennt 
1 of lt 1 30 311 
Jeweten-t - ee eee +---+~--~| 
| 32] 331 | 621 631 
|ennten-t - - em eee t---+-~- | 
|Jeente--+t - - te-Ht—-nt 
17041705! 173417351 
Jercte--t - - - ot tenat-—= | 
173617371 176617671 
temctem-t - oe ree ta—-t—-—+ 


Fig. 1. Graphics I Name Table Mapping 
The figure illustrates the pattern positions on a T.V 
screen with the VDP in Graphics I mode. The number 
associated with each position maps to the entry 
(offset) within the Name Table. The Oth entry in 
the Name Table maps to the pattern position occupying 
the top left corner of the screen. 


The Pattern Table determines which pixels will be turned on 
within a pattern. Each entry in the Pattern Table is eight 
bytes long. The first byte of an entry defines the pixel 
arrangement of the top row of a pattern, the second byte the 
second row and so on. A 'l' bit specifies a pixel that is on 
and a 'Q' bit specifies a pixel that is off. The offset of 
an entry into the Pattern Table (i.e. the entry number) 
forms the 'name' of the pattern. A pattern can be displayed 
on the screen in any pattern position by writing its name 

(offset) to the appropriate entry in the Name Table. The 
number of patterns available in the Pattern Table depends on 
the mode of the VDP. 


Spec. 50-90020490 Page 1 - 11 June 8, 1984 


VIDEO DISPLAY PROCESSOR 


The VDP is capable of producing fifteen colours plus 
transparent. The Colour Table determines the colours of the 
pixels defined in the Pattern Table. The high order nibble 
of a byte in the Colour Table defines the colour of the '1' 
bits in the associated byte of the Pattern Table. The low 
order nibble defines the colour of the '‘'O' bits. The 
resolution of the mapping from Colour Table to Pattern Table 
is dependent on the mode of the VDP. The colours associated 
with each 4 bit nibble are shown in Table l. 


The base addresses of the VRAM tables are derived from the 
values contained in the VDP's write-only registers, and are 
subject to restrictions dependent on the mode of the VDP. 
The base addresses are defined by calling the specific 10S 
routine for that table, which will set the correct bits in 
the appropriate VDP register. This process does not require 
a knowledge of the register addressing scheme. 


HEX VALUE COLOUR 
Transparent 
Black 

Medium Green 
Light Green 
Dark Blue 
Light Blue 
Dark Red 
cyan 

Medium Red 
Light Red 
Dark Yellow 
Light Yellow 
Dark Green 
Magenta 
Gray 

White 


QAONWPoODIAUBWNrHO 


Table 1. Colour Assignments 
The 4 bit hex values in the first column 
produce the colour in the second column 
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3.2.1 REGISTERS 


The VDP is equipped with eight write-only registers and a 
single read-only status register. The write-only registers 
are used to define the mode of the VDP, table addresses in 
VRAM, and the backdrop colour. All access to these registers 
is by way of calls to routines in the IOS. Descriptions of 
these routines can be found in the section on BOS calls. 


The write-only registers may be loaded with the IOS routine 
VREGWR. Specialized routines are provided for specifying 
VRAM table addresses. In the NPC environment a RAM image of 
the write~only registers is maintained, allowing examination 
of register contents. The registers may be 'read' by calling 
VREGRD, or with specialized routines (see IOS document). 


REGISTER 0 
REGISTER 1 


These two registers contain VDP option control bits. In 
practise, they are not written to directly with VREGWR, but 
rather are accessed through specialized routines. VSETXT is 
called to set the appropriate bits to place the VDP in TEXT 
mode. Other routines are VSETG1 (Graphics I) and VSETG2 
(Graphics II). 


The VDP also has a 'vertical blanking' option (the video 
screen is “blacked out") which is selected in register 1. 
The screen may be blanked with no effect on VRAM by calling 
the IOS routine VBLKON. The screen is restored with VBLKOFF. 
Other bits in register 1 determine the size and magnifica- 
tion of sprites (see 3.2.6 SPRITES). 


REGISTER 2 


Register 2 defines the base address of the Name Table. The 
address is set by calling VNAMEST. 


REGISTER 3 


Register 3 defines the base address of the Colour Table. The 
address is set by calling VCOLRST. 


REGISTER 4 


Register 4 defines the base address of the Pattern Generator 
Table. The address is set by calling VPTRNST. 
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REGISTER 5 


Register 5 defines the base address of the Sprite Attribute 
Table. The address is set by calling VATRIST. 


REGISTER 6 


Register 6 defines the base address of the Sprite Pattern 
Generator Table. The address is set by calling VSPRIST. 


REGISTER 7 


The high order 4 bits of register 7 define the colour code 
of ‘1' pixels in Text mode. The low order bits define the 
colour code for '0' pixels in Text mode and the backdrop 
colour in all modes. Register 7 is loaded by calling 
VREGWR. 


STATUS REGISTER 
The status register contains the following flags. 


F - The Interrupt Flag is set at the end of the raster 
scan of the last line of the display. It is reset to 0 
after the VDP Status Register is read or the VDP is 
reset. 


Cc - The Coincidence Flag flag is set whenever two 
Sprites have '‘'l' bits at the same screen location. 
(see 3.2.6 SPRITES). 


5S -~- The Fifth Sprite Flag is set whenever more than four 
sprites are displayed on the same horizontal line. The 
number of the fifth sprite is also loaded into the VDP 
Status Register. (see 3.2.6 SPRITES). 
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2 TEXT MODE 


As is implied by the name, Text mode is primarily for 
textual applications. The Name Table and Pattern Table are 
used to define the appearance of the screen. The Colour 
Table is not used. Patterns are 6 X 8 pixels, which allows 
for an increase to 40 characters per line. The Name Table is | 
960 (40 X 24) bytes. The Pattern Table contains the library 
of text patterns to be displayed. It is 2048 bytes long, 
consisting of 256 eight byte entries. Since each text 
position is only 6 pixels wide, the two least significant 
bits of each row of the pattern are ignored. There can only 
be two colours for the entire screen, one colour for all of 
the 'l' bits, anda second colour for all of the '0' bits. 
The colours are defined in VDP register 7 (see 3.2.1 
REGISTERS) . 


Typically, text patterns are loaded into the Pattern Table, 
such that the entry number corresponds to the ASCII code for 
the letter. For example, the ASCII code for the letter 'A!' 
is 65 (decimal). With the eight byte pattern for the letter 
'A' occupying pattern number 65 in the Pattern Table, the 
letter can be written to screen pattern position 3 by 
writing 65 to the third entry in the Name Table (Figure 2). 


Text mode allows for 40 characters per line on a T.V 
display. However, because of T.V. overscan, characters 
should not be written to columns 0,1,38 or 39. This 
effectively reduces the display to 36 characters per line. 


3.2.3 GRAPHICS I MODE 


Spec. 


The VRAM tables that are used to generate the screen image 
for Graphics I mode are the PATTERN NAME TABLE (Name Table), 
PATTERN GENERATOR TABLE (Pattern Table) and COLOUR TABLE. 
The Name Table determines the screen position for a pattern. 
The Pattern Table determines which pixels within a pattern 
will oe turned on. The Colour Table determines the colour of 
a pixel. 
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The VDP divides the screen into 8 X 8 pixel patterns, 
meaning that the Name Table has 768 one byte entries. The 
Pattern Table contains a library of patterns that may be 
placed in any pattern position on the screen. The Pattern 
Table is 2048 bytes long, consisting of 256 eight byte 
entries. There is amaximum, therefore, of 256 unique 
patterns which may be displayed at any one time in Graphics 
I. The offset of the pattern within the Pattern Table forms 
the name of the pattern. To display a pattern at a specific 
position on the screen, the pattern name is written to the 
appropriate entry in the Name Table. 
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NAME TABLE 
toon n een + <-- 
tennnn-n- + <-> 
1 (65) } 
to-n--H--- + 
poneeocat + xe 
| (66) | 
te------- + 
fooene-=- + <o- 
| | 
toma nnnn + 


ENTRY 


ENTRY 


ENTRY 


ENTRY 


T.V. Display has 


and 'B' 


(pattern 


95 


959 


tat 
66) 


(pattern 65) 
in position 95. 


PATTERN TABLE 


1000000--| 
1[001000--1 
1010100--| 
1100010--! 
1111110--1 
1100010--| 
1100010--| 
1100010--1 


[000000--| 
[111100--| 
1100010-~! 
1100010--| 
1111100--| 
1100010--| 
1100010--! 
1111100--] 


in screen 


ENTRY 0 


ENTRY 65 


ENTRY 66 


ENTRY 67 


ENTRY 255 


position 3, 


and Pattern Table Mapping in 


Mode 
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The colours of pixels are specified in the Colour Table. The 
colour table contains 32 one byte entries. Each entry 
defines two colours, the high order nibble of each entry 
defines the colour of the 'l' bits, and the low order nibble 
defines the colour of the '0' bits. The first entry in the 
Colour Table defines the colours for patterns 0 - 7, the 
second entry for patterns 8 - 15 and so on. This scheme 
imposes the following colour restrictions: 1) any one 
pattern can only display two colours and 2) changing the 
colours for one pattern implies a colour change for the 
seven other patterns within the colour group. 


3.2.4 GRAPHICS II MODE 


Graphics II mode is similar to Graphics I mode except that 
the Pattern and Colour Tables are longer. 


The Pattern Table is expanded to 6144 bytes, allowing for 
768 unique patterns, one for each pattern position on the 
screen. Since the one byte entries in the Name Table allow 
for a maximum of 256 unique entries, Graphics II segments 
the Name Table into three blocks of 256 names each such that 
the first block maps pattern names to the upper third of the 
screen. The second and third blocks map pattern names to the 
middle and lower thirds of the screen respectively. The 
Pattern Table is similarily segmented. Entries in the first 
third of the Name Table map to patterns in the first third 
(2048 bytes, 256 patterns) of the Pattern Table. 


The Colour Table is also expanded to 6144 bytes. There are 
768 eight byte entries. Thus, there is one eight byte entry 
in the Colour Table for each eight byte entry in the Pattern 
Table. The high order nibble of each byte defines the colour 
of the '1' bits in the corresponding byte of the Pattern 
Table. The colour of the '0' bits is defined by the low 
order nibble. Thus in Graphics II mode, two colours may be 
defined for each row (byte) of a pattern. The Colour Table 
is segmented into three equal parts in the same manner as 
the Pattern Table. 


3.2.5 MULTICOLOUR MODE 


Spec. 


The VRAM tables that need to be allocated for Multicolour 
mode are the Name Table and Pattern Tables. The Colour Table 
is not used, colours are derived from the Pattern Table. As 
Multicolour mode is rarely used, a complete description is 
not provided in this document. Further information may be 
found in the Texas Instruments 9900 Data Manual. 
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The pattern plane is divided into blocks of 4 X 4 pixels (64 
X 48 blocks). The colour of each block can be any one of the 
fifteen video display colours plus transparent. The backdrop 
and sprite planes are active. 


The Name Table consists of 768 one byte entries. The name 
points to an 8 byte segment of VRAM in the Pattern Generator 
Table. The colour to be displayed is determined by the 
information contained in the Pattern Table. 


3.2.6 SPRITES 


Spec. 


Sprites are special animation patterns. Up to 32 sprites are 
available, one for each of the sprite planes. Sprites may be 
used in Multicolour and Graphics modes, but not in Text 
mode. Each of the sprites can cover an 8 X 8, 16 X 16, or 32 
X 32 pixel area on its plane. Any part of the plane not 
covered by the sprite is automatically transparent. All or 
part of each sprite can also be transparent. The highest 
priority sprite is 0, the lowest priority is sprite 31. All 
sprites are of higher priority than the pattern and backdrop 
planes. The location of a sprite is defined by the top 
leftcorner of the sprite pattern. The sprite can be easily 
moved pixel-by-pixel by redefining the sprite origin (I0S 
call SPMOVE). 


The Sprite Attribute Table and the Sprite Generator Table 
are allocated in VRAM. These tables are the sprite 
equivalents of the Pattern Name Table and Pattern Generator 
Tables. Each entry in the Attribute Table is four bytes 
long, with one entry for each of the 32 available sprites. 
The first byte of an entry defines the vertical position of 
the sprite from the top of the screen in pixels. Values 
between -32 and 0 allow a sprite to bleed in from the top 
edge of the backdrop. A value of -1 causes the sprite to be 
positioned at the top of the screen, touching the backdrop 
area. The second byte defines the horizontal position of the 
sprite from the left edge of the display. A value of 0 
positions the sprite against the left edge of the backdrop. 
The third byte defines the name of the Sprite. This name 
maps to the Sprite Generator Table in the same way patterns 
are mapped from the Name Table to the Pattern Table. The low 
order four bits of the fourth byte contain the colour code 
for the ‘'1l' pixels of the sprite ('0! pixels are 
transparent). The most-significant bit of the fourth byte is 
the Early Clock Bit. When set to 'l', the position of the 
Sprite is shifted to the left by 32 pixels, allowing the 
Sprite to bleed in from the left edge of the display. 
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The Sprite Generator Table has up to 256 eight byte entries, 
for a maximum of 2048 bytes long, and is equivalent in 
function to the Pattern Generator Table. The I0S routine 
VSETSP is used to set the size and magnification of the 
sprites. Sprite size can be either 8 X 8 or 16 X 16 pixels. 
With 8 X 8 pixel sprites, the Generator Table uses eight 
bytes to define the sprite. When 16 X 16 sprites are used, 
the Generator Table requires 32 bytes. A16 X16 sprite is 
effectively divided in to four equal quadrants, with the 
bytes in the Generator Table being mapped to the screen as 
shown in Figure 3. The sprites can also be magnified one or 
two times. With a magnifaction factor of two, each bit in 
the Generator Table is mapped into 2 X 2. pixels on the 
screen display. 


There is a limit of four sprites on any horizontal line. If 
more sprites are positioned to the same line, the four 
highest priority sprites are displayed normally. The fifth 
and subsequent sprites are not displayed on that line. The 
fifth sprite flag is set and the number of the fifth sprite 
is loaded into the VDP Status Register. 


A value of DO (hex) in the vertical position field of an 
entry in the Sprite Generator Table terminates sprite pro-~ 
cessing. This allows programmers to blank part or all of the 
sprites. The IOS routine SPMARK will write DO (hex) to any 
sprite, and marks the end of the active sprites in the 
Attribute Table. 


Whenever two active sprites have '1l' bits at the same screen 
location, the coincidence flag in the VDP Status register is 
set. 
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SCREEN DISPLAY OF 
SPRITE PATTERN 


SPRITE GENERATOR 
TABLE ENTRY 


Fig. 3 Sprite Generator Table Mapping 
for 16 X 16 (1X magification) 
sprites. 
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3.2.7 VRAM TABLE ADDRESSES 


There are certain restrictions on where tables may be 
located in VRAM, dependent on the mode of the VDP. For 
example, in Text mode, the Pattern Table is 2048 bytes 
long, and must start on a 2 Kilcbyte boundary in VRAM. 


VDP MODE TABLE LENGTH (max) VRAM BOUNDARY 
Text Name 960 1K 
Pattern 2048 2K 
Graphics I Name 768 1K 
Pattern 2048 2K 
Colour 32 64-byte 
Sprite Attribute 128 128-byte 
Sprite Generator 2048 2K 
Graphics II Name 768 1K 
Pattern 6144 8K 
Colour 6144 8K 
Sprite Attribute 128 128-byte 
Sprite Generator 2048 2K 


The conventions for the NPC environment are that the 
Pattern Table always starts at VRAM address 0. The Name 
Table is placed at the next available boundary. In 
Graphics II mode, the Pattern Table is located at VRAM 
address 0, and the Colour Table at 8192. 


Note that in Text and Graphics I modes several screens 
may be defined in VRAM with multiple Name Tables. Each 
Name Table starts ona.1K boundary. To display a 
particular screen, the address of the desired Name 
Table is written to VDP register 2 with the IOS routine 
VNAMEST. This is particularly useful for setting up 
several screens of text. 
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@ 3.2.8 GRAPHICS I EXAMPLE 
It is desired to place the following pattern at screen 
pattern position 255 (hex FF) in Graphics I mode using 


pattern number 8 in the Pattern Table. The pattern is 
to be black on a grey background. 


*% each * represents one pixel on the screen 


PATTERN TABLE 


entry 00 --> +-~------- + 
I I 
entry 08 --> +4-~~------ + (BIT MAP) 
@ t 81 | (10000001) 
! 42 I (01000010) 
I 24 | (00100100) 
| 18 | (00011000) 
! 18 { (00011000) 
! 24 I (00100100) 
| 42 I (01000010) 
| 81 | (10000001) 
tenn Heo + 
NAME TABLE COLOUR TABLE 
entry 00 ==> +--------~ + entry 0 --> +-------- + 
I I I | 
SrSressts + entry 1 <--> 4+-------- + 
° ° | 10 1 
. . to------- + 
entry FF --> t-~------ + _ . 
I 08 | . . 
ten~--- + 
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The '10' (hex) in the Colour Table sets the 'l1' bits in & 
patterns 8 - 15 to black and the '0' bits to transparent. To set 
the screen to grey, VDP register 2 is set to 'OE' (hex). 
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The Programmable Sound Generator 


AS previously mentioned, all sounds produced by the NPC are 
under the control of the AY-3-8910 programmable sound gen- 
erator (PSG). This device uses 14 registers to generate a 
variety of complex sounds. The PSG has three individual 
channels to produce the sound effects. 


Producing sounds using the audio generator may be divided 
into several sound generating blocks. They are: 


1) tone generators 
2) noise generator 
3) amplitude control 
4) envelope control 


The registers of the PSG are used to enable/disable each of 
these blocks and to select the parameters of the channel in 
the PSG To read or write to the registers of the sound chip, 
the IOS BOS routines AUDWR and AUDRD MUST be used. See 
section 4.3 


Register 0 and register 1 provide the period or frequency of 
the tone to be produced by channel A of the PSG. All 8 bits 
of register 0 is used but only the lower 4 bits of register 
l are used. This provides a tone frequency resolution of 12 
bits with register 1 containing the most significant 4 bits 
and register 0 providing the remaining 8 least significant 
bits. 


Register 2 and register 3 provide the period of frequency of 
the tone to be produced by channel B. Twelve bit resolution 
is provided with register 3 providing the most significant 4 
bits. 


Similarily Register 4 and register 5 provide the tone period 
for channel C with register 4 providing the most significant 
4 bits of the twelve bits. 
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The following diagram should clarify the above information. 


coarse reg fine reg 
[ 31 21 11 Ol | 71 61 51 4% 31 21 11 0} 
reg 1,3,5 reg 0,2,4 


111/101 91 8! 71 61 51 4! 31 21 11 O} 


tone value of the channel 


There are two formulae that relate output tone frequency to 
the value in the twelve bit register. They are: 


f= 223,750 
tp 


and 
tp= 256ct + ft 


Where 
f£ = the frequency of the sound to be generated 
tp= the tone period to be written to the registers 
ct= the coarse tune register (registers 1,3,5) 
ft= the fine tune register (registers 0,2,4) 


Register 6 provides the tone period of the noise to be 
generated. It uses only the least significant 5 bits of 
register 6 and is the only register controlling the noise 
frequency. 


Similarily, the freqency of the output tone may be related 
to the noise period by the following formula: 


f= 223750 
np 
Where f£ the frequency of the noise to be generated 


np the noise period to be written to register 6 
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Register 7 enables and disables each of the three channels. 
Register 7 uses inverted logic therefore, a 1 indicates that 
the channel is disabled. 


channel Ic B Alc B A l 
function I NOISE | TONE l 
{716t1514t13 1242110 4° «-register 7 


Bits 7 and 6 are not used for generating sounds. 


Register 8, 9 and 10 controls the amplitude for channels A, 
B, and C respectively as well as the envelope pattern. 


If bit 4 is zero then the least significant 4 bits provide 
the amplitude (volume) of the channel's sound. This provides 
16 levels of amplitude with 15 being the greatest and 0 
producing no sound. 


If bit 4 is 1 then envelopes are enabled and amplitude of 
each channel is determined by the envelope pattern as 
defined by the lower four bits of the register. 


The remaining registers 11, 12 and 13 provide envelope 
control. There are two ways of controlling envelopes. First 
is to vary the frequency of the envelope using registers 11 
and 12, the second way is to vary the shape and cycle 
pattern of the envelope. 


The envelope period may be resolved to 16 bits by combining 
registers ll and 12. Register 12 provides the most 

significant 8 bits and register 11 provides the least 
Significant 8 bits. As before, 2 formulae may be used to 
relate the envelope period to the output envelope frequency. 
They are: 


f= 13984 
ep 
and 


ep= 256ct + ft 


Where 
£ =the desired envelope frequency 
ep =the envelope period 
ct =the coarse tune register (reg 12) 
ft =the fine tuning register (reg 11) 
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Register 14 controls the envelope shape or cycle. Only the @ 
lower four bits of the register are used. Each bit has an 
individual function. 


[ 71 6f 51 41 3) 21 11 Ol register 14 


| 

Ike) ic eeeee hold 

[ul AaSessas alternate 
| seeeean---- attack 

[Sr esSSreaSes= continue 


If hold is set to 1 the envelope is limited to one cycle and 
holds the current state of the envelope counter. 


If alternate is set to 1 the envelope reverses the direction 
after each cycle. 


If attack is set to 1, the envelope will count up. 
If attack is set to 0, the envelope will count down. @ 


If countinue is set to one the cycle pattern will be defined 


by the hold bit otherwise the envelope counter will reset to 
zero and then hold. 
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4.0 THE INTERNAL OPERATING SOFTWARE 


The INTERNAL OPERATING SOFTWARE (IOS) is a versatile operating 
system used to run the application software. It provides a 
standard interface and sets of common routines to link the 
applications to the hardware of the NPC. 


The IOS may be broken into 2 distinct portions for the 
application programmer. They are: 


1) The Downloadable Operating Software (DOS) 
2) The basic operating software (BOS) 


Downloadable Operating Software 


This is the highest layer of the internal operating software. It 
interfaces to the BOS and applications programs to provide: 


Configuration Identification 

Functional Level I/O handling 

Calling of I/O handlers and device control code 
Interrupt and task handling control 

Common Entry Points for Applications 

I/O Routing 


oooo0o 0 


Basic Operating Software 


This level of the operating system provides the key operating 
control software for the NABU P.C.. It interfaces to the 
Downloadable Operating Software and applications programs. The 
BOS provides: 


o Functional Level I/O handling 
o Common entry points for applications. 
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4.1 CONVENTIONS USED BY THE INTERNAL OPERATING SOFTWARE 


The IOS memory map structure is similar to that of Digital 
Research's CP/M operating system. Thus, any CP/M system may be 
used as a development system for the NABU P.C. Programs written 
in a high level language compatable with CP/M will run under the 
IOS. However there are differences between CP/M and IOS. Not all 
CP/M calls are implemented in the basic IOS and the stack 
requirements are different. 


The memory map below I0S is layed out as follows: 


BASE to FFFFH| reserved for I0S | 
[Reese sSeeeSshe cosas ssseee | 

BASE-1 1 Applications Program | 
0100 hex: | Area + Stack(s) I 
saa atheros ah aa I 

OOFF hex: | Reserved Area for 10S | 
000B hex: [| | 
lesereresssasaisssss-tsSSeTS I 

QOOA hex: | | 
0008 hex: | Jump to DOS IOS calls | 
| mone nan een | 

0007 hex: | Jump to BASE | 
0005 hex: I[(the jump to DOS CPM calls) | 
0004 hex: | reserved for I0S | 
0003 hex: | | 
leoenmsssseee sss sas = s=-S ss | 

0002 hex: | Jump to IOS warm start | 
0000 hex: ------ nnn nnn nn nnn nnn n= 


(Note that there is a data area within IOS that is reserved for 
the use of applications. This area is unique in that the memory 
contents remain intact across resets and warm starts. This can 
be useful for "chaining" programs. This area is at locations 
FF80 (HEX) through FFDF (HEX) inclusive.) 


Applications programs interface to the IOS through three entry 
points only. These are locations 0000H, 0Q005H and 0O008H. A 
discussion of each location now follows. (Note also that 
applications may also enter IOS routines through BOS calls. See 
section on BOS Calls elsewhere in this manual.) 
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SUMP to LOCATION 0000 Hex 


An application program that CALLs or JUMPs to location 0 will 
cause a warm start of the IOS. This CALL _is used when an 
application program is finished running and wishes to return to 
whatever human interface program invoked it. In order to be 
compatable with CP/M, this entry point jumps to the WARMBOOT 
entry in a jump table which is identical to CP/M's BIOS Jump 
Table. It is recommended that applications programmers avoid 
attempting to use the BIOS Jump Table. The IOS is structured this 
way to be compatable with CP/M applications programs and to 
provide support expansion to the IOS. 


CALL to Location 0005 Hex 


Location 0005 Hex is the same as the standard CP/M entry point. 
Details on this entry point are found in the section on CP/M 
Compatible Calls. Note that locations 6 and 7 contain a pointer 
to BASE, the first location used by the IOS. This allows applic~ 
ations programs to determine how much memory is available. BASE 
may vary between different versions of the I0S. 


CALL to Location 0008 Hex 


Location 0008 Hex is the entry point into the DOS IOS Calls. 
These calls are detailed in the section on DOS Calls. This entry 
point has the same calling conventions as the entry point at 
location 0005, except it is used for non-CP/M compatable operat~ 


ing system calls. Note that locations 9 and A do NOT point to 
BASE. 


When the MAIN MENU starts executing it will find the following 
initial conditions have been set: 


o The Stack Pointer is set to BASE 
(the first PUSH will write to BASE-1 and BASE-2) 


oO All other 2-80 registers are undefined 


Oo All clock processing turned on 
-Flashing Cursors Enabled 
-Clock User Task Handling Enabled 
~Real Time Clock Incrementing Enabled 


Oo The Video Chip is set to text mode. 
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o Logical to Physical I/O Routing Set up to emulate 
Standard CP/M assignments: 
-Video Device Location 1 set to: 
38 wide by 24 deep window with 
underline flashing cursor 
~Console Output Routed to Video 
Device Location 1 (see window above) 
-Console Input Routed to Human Interface 
Device Location 1 (Keyboard) 
-List Routed to Printer 
~Reader Routed to Human Interface 
Device Location 1 (Keyboard) 
~Punch Routed to Video 
Device Location 1 (see window above) 


After the MAIN MENU program gains control, it has the ability to 
alter the initial conditions for the application program which is 
to be loaded. For a complete list of the initial conditions as 
set up by the MAIN MENU program, please consult the Master 
Directory and Main Menu Specification 02-90020480. 


4.1.1 Stack Operation and Requirements 


The IOS only supports a single stack which is used by both the 
IOS and applications programs. This is different from CP/M which 
has two or more stacks, one or more used by CP/M and one for the 
application. Note that the IOS initializes the stack pointer to 
BASE so the stack will start at the highest available memory 
location and build down. The number of bytes of stack required by 
IOS depends on the number of peripheral devices attached. For 
the basic I0S, up to 64 bytes may be used by the operating 
software. This means an application program must be sure to 
allow for a stack size 64 bytes larger than what the application 
requires. The addition of peripherals to the NPC may increase the 
minimum stack requirement. 
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452 €PA¢M Compattbie Catis 


Phe FOS supperts a number ef eaiis whieh are simiiar te standard 
€P¢M non-disk 46 eatiss: Ne disk oriented catis are supported: 
Phe €P/M compatibie eaiis that are provided are for resetting the 
systems and fer perferming 20 from the tegieni devices CONSOLE, 
READER; PUNCH and bESP> 


Phe FOS BOS EP‘M compateabie E46 faetiities deai onty with iegteat 
deviees; ‘erg> CONSOLE; BEST, READERZ PUNCH} > Phe 0S =4O 
Handiers operate with speeifie physieat deviecess tthe 65 
Hateaches" the itegteat deviees to the physteat devieesz Por 
exampiey this atiews an ASCIE character te be sent te the tegieat 
deviee and it ends up at the physieai devieest 


Phe feiiewing tegieat deviees are defined> 


KE¥BOARD? timput pertien ef CONSOLE} 
SERBEN? teutput pertien ef CONSOBE} 
BESP+ feutputy 

REABER? tinpet device} 

PUNCH toutput device} 


wm WH © 


Phe fotiewing physical deviees are defined: 


HUMAN EINPERPAECE — 


RBEYPAB+ 6: tinpeut> 
TOYSPEER t+ 62 +téinput? 
JOXSPEEK 2+ 83 ténput} 
SCREEN WENBOW #1- #2 fontpet} 
PRENFERS 23 toutput} 


Assignments ef physiteait deviees te tegient deviees are performed 
by using the i/6 Router Entry Petnets When e@& pregram begins 
exeeution the fetiowing tegieat to physieai attachments are medes 


BOGTEAE PHYSTEAL 
KEYBOARD KEYBOARD 
SEREEN SEREEN WENBOW #2 
bis? SEREEN WENDOW #3 
READER SERBEN WENBOW #+ 
PUNCH SEREBEN WENBOW #+ 


Note that SEREEN WENBOW #1 +5 defined by the system and ts 
avatiablte te the apptieetion when tt starts, 


Phe €P/M eompatibie eatis previded in the FOS threugh teeatten 5 
ate as fotiewss 
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SYSPEM-RESEP teati number 66H} 
-performs same funmetion es a jump te teeatton 8660 Hex 
-entry paremeterss 
€ Register: 66 Hex 
~ts not fe-entreant 


EONSOBE-ENPET . teati number 61H} 
reads the next character from the tegteat eonsete with eche 
Phe eati dees net return untii a eharaeter ts ready> 
{Phis eatt witit onty eaecept EP‘M compatibie ASEFE 
eharaeterss Ff the 4¥ES" key ts hity a "¥2 ts returneds Ff 
the "no" key is hit a IN" ts returnedy Ati other key eodes 
above 7PH ate tqnered=t 
~entry parameters: 
€ Regtster+ 6+ Hex 
-Returned Vatues+ 
A Register: Chareeter Enput 
-ts net re-entrant 


€ONSOLE-OUPPEP teati number 62H} 
-otttputs e eharacter te the tegteat econsgete 
4Stnee the defauit physieat eonsete driver ts BOS eaitt 
@a2 and O0A3 eonsuit the speetfieatien fer BOS eati ABH 
for contrei eharaeter tnterpretations} 
~entry parameters: 
€ Regtster+ 62 Hex 
B Register: Chareeter te be eutpet 


READER-ENPEP teaii number 63H} 
-geet a byte from the tegicat PAPE reader eontret wit 
not return te the eetiing pregram untti the eharaeter 
has been read: 
{Phis eatti wiii enty accept €P*/M eompatibte ASELE 
ehareeters: Tf the “¥8S" key ts hity a “¥" +3 returned. Ff 
the "NO" key ¢8 hit a IN" ¢s returned: Ati other key codes 
above 7PH are tgnereds} 
~entry parameters: 
€ Register: 63 Hex 
-returned vatuer 
A Register: eharacter read 
-ts net re-entrant 


PEUNCH-OU PPE? teati number @4H} 
~output a byte te the tegieat PAPE puneh 
tSinee the defauit physteat eensete driver ts BES eatti 
O@A2 and 8A3 econsuit the speetfieation fer BOS eati A3ZH 
for ecentreit character interpretations} 
-entry parameters: 
€ Register: @4 Hex 
B Register: character te be output 
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bESP-OEPPEP teaiti number @5H} 
~oueput ea eharacter te ehe tegieat fist device 
~entry parameters: 
€ Register: 85 Hex 
B Registers character to be exutput 


BIRHEP-CONSOnE-FO teati number 06H} 
~prevides tnadorned 7/0 from/to the tegieat eonsete 
Upon entry7 the & register either centains an OPP Hex; 
denoting a econsete input request; of a eharaecter to be 
outputs FF the input vatue if GPP Hex; then the 
funettens returns with the A regtster set to 80 tf no 
eharaetetr ts ready at the tegiea: otherwise the A 
register £8 set to the chereecter vatue input frem the 
tegteai eonsetes 
{Pris eati witi oenty aceept CP/M compatibie ASETE 
eharecters: Ff the 4¥ES" key ¢8 hit; a 8¥2 ts returned: Ff 
the "NO" key ts hit a 8N" ts returneds Aki ether key codes 
above 7PH are tgnereds} 
4Sinee the defauit phystcat eensete driver ts BOS eati 
6Aa2 and 0A3 econsuit the speeifteation fer BOS eat AZH 
fer econtrei character tnterpretations}+ 
centry parameters: 
€ Register: 06 Hex 
& Registers PP Hex tinmput} er 
echereeter te be output 
-returned vatues 
A Regtster: echareeter of 69 Hex tinpue} 
nething if eutpue 
~is net re-entrant 


PRINP-SPRENG teaii number 69H? 

“print a string te the iegieai eensete frem a buffer 
Phe character string stored in memory et the teeation 
pointed te by the DE register ts sent te the tegteat 
tensete: A 48+ 49 used as a detimiter to end the prtne 
strings 
tSinee the defauit physteat consete driver ts BOS eait 
OA2 and 043 eonsukt the speeificntion fer BOS eat aA3#H 
for contret eharacter interpretations} 

ventry parameters: 

€ Register: 99 Hex 
BE Register: peinter te string 
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READ-CONSOGLDE-BUPPER +eati numker OAH} 
~read a tine of editied tegieat eonsete input te a buffer 
The input ts stored in the memory buffer pointer te by 
the DE register: Ff the buffer overfiews eensete input 
ts terminated: Phe format of the buffer iss 


MAX~BUP-SEZEs BYPE> 
NUMBER-OP-CHARACTERS-READ+ ~- BYTES 
CHARACTER-BUPFERs ARRAY TisTMAX-BUP-SIZB BYPES 


Phe 21602 key (9B Hex} er ENPRE ¢ +64 Hex} wiii terminate 
the input tines Phe BEHRTH key witi detete the prevtesty 
typed cheracter: 
{fhis eait wiii onty aceept €P/M ecompattbte ASELET 
characters; if the “¥8S" key ts hity a@ 4¥5 ¢9 setupneds F& 
the =NO” key ¢e hit a NZ is returned: Adi ether key ecedes 
above 7PE are ignoreds} 
~entry parameters: 
€ Registers OA Hex 
BE Registers Petnter te MAX-BUP-SEZE 
4MAX-BUP-SEZE must be set es wet} 
~returned values: 
€ensete Chareeters in Buffer 
NEUMBER-OP-CHARACTERS-READ set 
~is net re-entrant 


GEP-€ONSOLE-SPAPTUS -+teaii number OBH} 

~cheek to see if character has been typed at tegteat eensete 
~entry parameters: 

€ Register: OR Hex 
~returned vatue-: 

A Registers 66 Hex -Ne eharecter ready 

PP Hex —Cheraeter i¢ ready and waiting 

~ts net re-entrant 


EYO-ROUPER+ APPACH teati number 8AH} 
watetaehes a particular physteat device te a tegieat device 
~entry parameters: 

€ Register: 8A Hex 
& Register: PHYSEeaAn-pEYZCE 
B Register: HOGTECAL-BEYVTER 


Where HOGECAL-DEVEICE ts the byte vatue ef «4 tegteat 
device as tdentifted in the seetion above and 
PRYSECAR~BEVIEE ts the byte value of a Physteat devices 
Phts eat wiit eause ati subsequent 346 to the togiead 


device te be performed b : é 
Y : y the phystea} 4. = 
This cati ts avetiabie in the Bese ST pan Sear aae 
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4.2 INTRODUCTION TO DOS 


The highest (and simplest) level of access to the IOS for 
applications programs is through the Downloadable Operating 
Software (DOS). 


The entry points to the IOS use a standard calling convention and 
calling procedure. Each particular function is given a call 
number. This number is passed in the 72Z-80's C register. A 
function call may also accept zero, one, or two parameters as 
inputs and return zero or one value aS an output. These 
parameters are passed as follows: 


Function Number: Passed in C register if a BYTE 


Return Value: Returned in A register if a BYTE 
Returned in HL registers if a WORD 


One Parameter: Passed in E register if a BYTE 
Passed in DE register if a WORD 


Two Parameters: Passed in E register if a BYTE 
Passed in D register if a BYTE 


If more than 2 parameters need to be passed, then a dedicated 
data structure is implemented. 
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4.2.1 SEGMENT HANDLING ROUTINES 


4.2.1.1 INTRODUCTION 


The 10S provides the mechanism for interfacing with the data and 
programs that are found on the broadcast cycle. All data or code 
(program) which can be loaded at one time forms what is called a 
segment. Segment loads can be of varying size from a few bytes 
up to the NPC's available free RAM space. (By using segment load 
offsets, the application can manipulate data segments of much 
larger size.) 


The interface that IOS provides is composed of two components. 
The first is that we provide DOS entry points which perform 
different segment handling functions. The second is that the IOS 
contains a data structure called the segment control/status 
block. This block of data is the place where data is passed to 
the segment handler and where data is received from the segment 
handler. 


The following section will describe the theory or specification 
that the segment handler obeys. Following that are examples of 
how a programmer could use the segment handling functions. 


4.2.1.2 SEGMENT CONTROL AND STATUS BLOCK 


The IOS contains a data structure called segment control/status 
block. This block is used to pass information to and from the 
segment handler. This block resides inside the IOS and not in 
the application work space. 


The programmer gains access to address of this block using DOS 


call 87H. By using a template of the control block as described 
below, the block can be modified as needed. 
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@ CONTROL/ STATUS BLOCK 
STATUS I I 
I | 
BYTES TRANSFERRED! LS ! MS I 
I J | 
OPTIONS | I 
I I 
SEGMENT ADDRESS ! MS I I LS | 
! | I I 
BUFFER POINTER ! Ls I MS ! 
I | | 
BUFFER SIZE ! Ls ! MS I 
I | | 
CONDITIONS I | 
| I 
OFFSET | Ls I | MS I 
| : | | l 
Where: 
STATUS: - is a one byte variable 
& _ is an output variable set by segment handler 
- indicates the status of the segment operation as: 
1 busy doing operation 
0 Operation finished with no error 


MINUS NUMBERS 


BYTES TRANSFERRED 


Spec. 50-90020490 


a 
~2 
-3 


-4 
-5 


- operation finished with error 


tier not authorized 

segment buffer overflowed 

adaptor did not respond in time and 
segment handler timed-out 

segment contained a bad packet 
communication protocol failed between 
adaptor and P.C. 


is a two byte variable least significant 
byte first 

is an output variable set by segment 
handler 

indicates number of bytes transferred 
into segment buffer 
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OPTIONS = 


If: 
bit 0=0 


SEGMENT ADDRESS = 


RAM POINTER ~ 


is a one byte variable 

is an input variable initialized by the 
application prior to segment operation 
indicates information on how segment is 
to be loaded: 


control is returned immediately back to 
calling program after segment operation 
has started . 


control is returned back to calling 
program after operation is finished. 


data segments will be loaded into RAM. 
data segments will be loaded into VRAM. 


are reserved and should be 0. 


Is a3 byte variable, most significant 
byte first. 


Is an input variable provided by the 
application, normally based on 
information from the directory. 


Indicates the segment identity to be 
loaded. 


This will be a number from 3 to 7FFFFFH. 


Is not required for all segment 
operations. 


Is a 2 byte variable, least significant 
byte first. 


Is an input variable provided by the 
application. 


Indicates where the segment or the 
status information is to be loaded. 
This would be some area inside the 
application or in VRAM. 


Is not required for loading segments 
where segment contains its load 
address. 


Spec. 
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@ RAM SIZE - Is a 2 byte variable, least significant 
byte first. 


- Is an input variable provided by the 
application. 


= Indicates size of buffer in bytes; as 
pointed to by buffer pointer. 


- Only required if buffer pointer is 


required. 
CONDITIONS - Returned. Can be ignored. 
OFFSET - This value (3 bytes) represents the num-— 


ber of bytes, from the beginning of the 
data segment, to ignore when loading the 
segment (an offset to the first loadable 
byte). Ensure that this is zeroed if you 
do not wish an offset.) 


4.2.1.3 DOS INTERFACE 


@ The segment handler performs operations based on the segment 
control block being correctly initialized, and a call being made 
to a DOS entry point. 


*** NOTE *** In order for the segment loader IOS to properly 
interface with the Adaptor, the application 
program must NOT be within an interrupt protected 
area of code when making segment handler requests. 
Interrupts must be enabled and this implies that 
the call to the segment handler does not occur 
inside of a CRBEG — CREND code block. 

( See "Interrupt Structure and Tasking Support" 
for more information on  CRBEG, CREND and 
"Critical Regions". ) 
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The DOS call is made by initializing register C and "calling" to 
location 8&8. The following calls will be the ones used by 
applications. 


IF 
REG C = 80H Segment handler is reset 
REG C = 84H Segment is loaded and 
interpreted if necessary 
REG C = 87H Base address of control 


block is read 


All parameters passed and returned are made through SEGCST. 
SEGMENT HANDLER IS RESET Call Number 80H 


When this operation is invoked, any pending segment operation is 
ignored and the adaptor is reset to a known state. The segment 
control/status block does not have to be initialized because it 
is not used by this operation. 


SEGMENT IS LOADED AND INTERPRETED IF NECESSARY. Call Number 84H 


This operation attempts to load in a segment as indicated by 
segment address in the control block. If the segment is loaded, 
the segment header may be interpreted to help with the load 
address and the location where execution of code is to begin or 
continue. If the load is unsuccessful, error information is 
returned in the status byte. 


LOADING A DIRECTORY-ONLY SEGMENT 
The control block requires that: 


Options = 01 or 00 
Segment address contains the number of a directory segment 
Ram pointer and Ram size are not used 


The segment will be loaded into the directory area inside IOS. 
The previous directory will be overwritten and the IOS will be 
notified that a new directory is present. The code-to-load field 
in the segment header will have been 000000 indicating that this 
directory has no code associated with it. After the directory 
has been loaded in, control is returned to the calling program. 
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LOADING A CODE SEGMENT: 
The control block requires that: 


Options = 01 {for 00} 
Segment address contains the number code segment 
Buffer pointer and buffer size are not used 


The segment is loaded. The segment header contains the load 
address where the code is to be loaded. It also contains the 
Start address where execution begins in the code after it has 
successfully loaded. Just prior to execution beginning in the 
newly loaded code, initialization occurs. The stack pointer is 
set to just below IOS, all attached tasks are removed, and the 
keyboard and clock interrupts are enabled. 


LOADING A DIRECTORY WITH CODE-TO-LOAD 
The control block requires that 


Options = 01 
Segment address contains the number of the directory segment 
Ram pointer and Ram size are not used 


The directory portion of the segment is loaded into the I0S 
directory area. Then the code-to-load field in the segment 
header is checked. If the value is FFFFFFH, then a code segment 
complete with header will immediately follow the directory in 
this same segment. If the value is not 0 and not FFFFFFH, then 
the code segment specified by the value is loaded in. 


LOADING IN A DATA SEGMENT 
The control block requires that: 


Options = 01 or 00 

Segment address contains the number of the data segment 

Ram pointer contains the pointer to the area where the 

data is to be written 

Ram size contains the size of the area where data is to be 
written 

Offset is set to the number of bytes to ignore in the segment 
before loading (usually 0). 


The data is loaded into the buffer as specified. After the data 
has been loaded control is passed to the calling program. 
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LOADING IN A OVERLAY SEGMENT: 
The control block requires that: 


Options = 1 or 00 
Segment address contains the number of the overlay segment 
Ram pointer and Ram size are not used 


The overlay is loaded in at the load address specified by the 
segment header. After the segment has been loaded, control is 
returned to the calling program. 


BASE ADDRESS OF SEGMENT CONTROL/STATUS BLOCK IS READ. 
Call Number 87H 


The application is returned to the base address of the control 
block in the HL register pair. This will allow the programmer to 
place a template of the control block at that address in order to 
initialize the block as required. 


4.2.1.4 SEGMENT HEADERS 


Each segment requires some overhead to describe what the segment 
contains. The extra data is called a segment header. 


Segment headers have differing lengths. The minimum size of a 
header is 2 bytes long and the maximum size is 255 bytes. 


The first byte of each header always contains the length of the 
header (2-255) in number of bytes. 


The second byte of each header always contains the segment type. 
Four types of segments are currently defined: 


Type 0 = Directory segment with or without code-to-load 
Type 1 = Code segment 

Type 2 = Data segment 

Type 3 = Overlay segment 
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DIRECTORY SEGMENT HEADER 


LENGTH 
TYPE 00 
ENTRY WIDTH 

NUMBER OF ENTRIES 
“MS 


CODE-TO-LOAD | 


NAME LENGTH 


NAME 


Entry width is the width of the directory entries. Each 
directory entry has the same width. The width has a minimum size 
of 10 and maximum size of 255. (See section on directory calls.) 


Number of Entries is the number of directory entries. This value 
could have a minimum of one and maximum of 255. However since 
the maximum directory is 1000 bytes, the product of entry width 
and number of entries must not exceed 1000. 


Code-to~load is the field which indicates if code is to be 
loaded, and where this code can be found. If this value is 
FFFFFFH, then code follows the directory. All other values 
indicate the segment number of the code segment. 


Name length is the number of characters in the name of this 
directory segment. The minimum is 1 byte and maximum is 
255 bytes. 


Name is the actual ASCII name of this directory segment. 
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CODE SEGMENT HEADER 


LENGTH 1 8 it 
TYPE 1 | 
LOAD ADDRESS MS past 
START ADDRESS | MS ee LS 


Load Address is a 3 byte variable, most significant byte first, 
which tells the segment handler where to place the code. 
Currently the first byte is always 0. 


Start Address is a 3 byte variable, most significant byte first, 
which indicates where execution begins. Currently the first byte 
is always 0. 


DATA SEGMENT HEADER 


LENGTH 2 


| 

| 
TYPE 1 2 

{ i 


This header is the shortest one. Its purpose is to notify the 
segment loader that it is a data segment. 


OVERLAY SEGMENT HEADER 


LENGTH 1 5 | 
I I 

TYPE ! 3 4] 
fe | 

LOAD ADDRESS [us | {Ls | 
| I 


Load Address is the address at which this overlay is to be 
loaded. It is a 3 byte variable, most significant byte first. 
Currently the first byte is always 0. 
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4.2.1.5 EXAMPLES 


In order to help illustrate the calls to the segment handler, 
examples written in assembler are included. They are arranged in 
some order from least difficult to more difficult. 


>>>> ABORTING A SEGMENT LOAD <<<< 


SCENERIO: The program has requested a large data segment, 
and decides that the data is not required. The 
segment load is aborted. 


CODE: LD Cc, 80H 
CALL 8 


>>>> RESET SEGMENT LOAD DEVICE <<<< 


SCENERIO: Although it is not required, a program may choose 
to reset the segment load device prior to loading 
a segment. 


CODE: LD C, 80H 
CALL 8 
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>>>> LOAD A DATA SEGMENT <<<< 


SCENARIO: The program has determined that it needs to load 
data segment “tax-table". It has searched through 
its directory and found that "tax-table" is data 
segment no. 000234H. The table is to be loaded at 
location 8000H. Buffer is 1200H bytes long. 

CODE: 

LCB: create a local 

STATUS: DB 0 control block 

BYTES: DW 0 

OPTIONS: DB 1 return control after load 
finished 

SEG ADR: DB 00,02H,34H segment no.= 234 

RAM PTR: DW 8000H buffer pointer 

RAM SIZE: DW 1200H buffer size = 1200 


CONDIT: DB 0 
OFFSET: DB 0,0,0 
BASE: DW 0 
START: LD C, 87H 
CALL 8 

LD (base), HL 
EX DE, HL 


LD HL, LCB 

LD BC, BASE-LCB 
LDIR 

LD C, 84H 

CALL 8 

LD HL, (base) 
LD A, (HL) 

CP 0 


Ne Me Se Ne Ne Se Se Se Ne Se Se Se Se Se Nn Se Se Se Se 50 Se Ne Se Ne we Se Ne 


condition byte (returned) 

load from beginning of segment 
value of base address 
get base address of 
block 


segment 


temp. storage 

DE=PTR to IOS control block 
HL=PTR to local control block 
# of bytes to move 

IOS control block initialized 


load data file 


check for error 
restore base address 
read status 

if status = 0 

then no errors occured 
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@ >>>> LOAD AN OVERLAY SEGMENT <<<< 


SCENERIO: The program requires that an overlay be loaded and 
a subroutine in the overlay executed. Overlay 
segment number is 54321 Hex. 


CODE: 
LCB: local control block 
STATUS: DB 0 
BYTES: DW 0 
OPTIONS: DB 1 return control after load 


finished 

seg number = 54321 
don't care 

don't care 


SEGADR: DB 5H, 43H,21H 
RAM PTR: DW 0 
RAM SIZE: DW 0 


BASE: DW 0 Storage for base address 
START: LD C, 87H get base address 
CALL 8 
@ LD (BASE), HL temp. storage 


EX DE, HL 
LD HL, LCB 


move local block 
to IOS block 


LD BC, 7 

LDIR 

LD C, 84H load overlay segm 
CALL 8 


LD HL, (BASE) 
LD A, (HL) 


check status 


CP 0 
JR NZ, ERROR 


if status NE 0 
then go to error 


Se se Ne Ne Ne Se Se SB Ne Se Se Ne Se Se we Se Ne Se Se te Se Se Ne Se Ne te Se Ne we Ne 


CALL SUBROUTINE else do subroutine 
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>>>> LOAD A CODE SEGMENT <<<< 


SCENARIO: A code segment is to be loaded in and executed. 
If an error occurs, during loading, execution is 
to re-boot the system. Segment number is 1234H. 


CODE: LCB: local control block 
STATUS: DB 0 
BYTES: DW 0 
OPTIONS: DB ¢] return control 


immediately 
seg no. 1234 
don't care 
don't care 


SEG ADR: DB 0, 12H, 34H 
RAM PTR: DW 0 
RAM SIZE: DW 0 


START: LD C, 87H get base address 


move local block 


me Ne Se Se Se Ne Ne we So Ne Se Se me Se Ne Se Ne Ne Ne Ne 


LD HL, LCB to Io0S 

LD BC, 7 

LDIR 

LD C, 84H load code segment 

CALL 8 

JP 0 error occurred, reboot 


>>>> LOADING A DIRECTORY SEGMENT WITH NO CODE TO LOAD. <<<< 


Example is identical to loading an overlay segment. 


>>>> LOADING A DIRECTORY SEGMENT WITH CODE TO LOAD. <<<< 


Example is identical to loading a code segment. 
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4.2.2 DIRECTORY ROUTINES 
4.2.2.1 INTRODUCTION 


Each application which requires segments off the cable will have 
a segment directory loaded into memory. The segment directory 
will be stored as a 1K buffer as part of the IOS. Each entry of 
the directory will contain information about one segment being 
transmitted on the cable. 


This section describes the format of the directory in memory, and 
the method that applications use to access information in the 
directory. 


4.2.2.2 FORMAT OF DIRECTORY 


The segment directory is stored in a 1K buffer in the IOS. The 
format of the information in the buffer is as follows: 


| 
DIRECTORY | 
SEGMENT 1 
HEADER I 


The DIRECTORY SEGMENT HEADER is the standard segment header as 
described in section 4.2.1.2.3. Following the header, are a 
number of entries, one entry per segment in the directory. 
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Each directory entry has the following format: 


TYPE | 1 BYTE 
wo - + | 
I OWNER | 1 BYTE 
|---------~--------- 1.2 
[ l 
I TIER LEVEL | 4 BYTES 
| | 
| -----~-~-~-~-------- | 
| SEGMENT ADDRESS ! 3 BYTES 
| | 
|-----~-------~----~- l 
| 
| 
| 
| NAME | 18 BYTES 
| | 
1 | 
| 
Jenne na---- === === 

RESERVED 4 BYTES 


TYPE and OWNER are each one byte values that are currently 
undefined in the NABU NETWORK. TIER LEVEL is a four byte value 
which gives the tier access information of the segment, each bit 
corresponding to a different tier level. The SEGMENT ADDRESS is 
a three byte value which gives the address number of the segment 
on the cable. This three byte value is the number that must be 
put into the SEGMENT ADDRESS of the SEGMENT CONTROL AND STATUS 
BLOCK when a request is made to load the segment off the cable 
(see section 4.2.1). 


The NAME of the segment is given by the applications programmer 
when submitting the segment to the APS. It can be up to 18 
characters long. In the directory entry the name is left 
justified and right padded with blanks. In most cases the 
application will know the name of the segment to be loaded, and 
search through the directory to find the segment address in order 
to request the segment off the cable. 


The last four bytes of each directory entry are reserved for 
system use and should not be used by the application. 
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4.2.2.3 ACCESSING THE DIRECTORY 


Multi-Segment applications require a means of loading overlays or 
data. The segment loader requires that a segment number or 
address be present in the segment control block. The user 
directory contains the information which links the segment name 
with the segment address. This directory is loaded into an IOS 
directory area. This is an internal 1K buffer. 


An application has one DOS calls available for accessing the 
directory: the routine to search through the directory for a 
particular entry. 


DIRECTORY SEARCH DOS CALL 88H 
PURPOSE: To search for a particular entry in the directory. 
PARAMETERS PASSED: C Register - 88H 

DE Register - Address of a Directory 
Search Block (see below). 
PARAMETERS RETURNED: All information returned is done so in 
the Directory Search Block as described 
below. 
DATA STRUCTURES: The Directory Search Block is a data 
structure declared by the application and passed to the 
I0S when the directory search call is made. the 
Directory search Block has the following format: 
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| MATCH PATTERN | 


NAME 


1 BYTE 
1 BYTE 
1 BYTE 


l BYTE 


4 BYTES 


3 BYTES 


(ENTRY WIDTH) - 9 BYTES 


The MATCH PATTERN is set by the calling application and is 
used to indicate which fields in the directory entry are to 


be searched for. The meaning of each 
MATCH PATTERN byte is as follows: 
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match TYPE 

match OWNER 

match TIER LEVEL 
match SEGMENT ADDRESS 
match NAME 

not used 

not used 

0 => search for first 
1 => search for next 
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If the N, L, TT, O or Y bits are set in the SEARCH BLOCK, 
this indicates that the corresponding fields of the search 
block are to be matched with the directory entry. For 
example, if the application wished to search for a segment 
with the name COSMOS, it would set the N bit, and reset the 
L, T, O, and Y bits. If the application wished to search 
for a segment with the name COSMOS and with owner 33, it 
would set the N and O bits, and reset the L, T, and Y bits. 


The S bit of the match pattern indicates whether to search 
for the first directory entry which matches, or the next 
directory entry after the last search. 


The ENTRY WIDTH gives the number of bytes in the search 
block following the ENTRY WIDTH byte. It is required to 
compute the number of characters in the NAME. 


The fields TYPE, OWNER, TIER LEVEL, and NAME correspond to 
the fields in the directory entry. The application will set 
these fields if it wishes to search the directory for a 
corresponding entry. For example, if the application wished 
to search for a segment with owner 33, it would set OWNER to 
33; if it wished to search for a segment called NEUTRON BOMB 
it would set NAME to 'NEUTRON BOMB’. 


When matching on NAME the application can use "wildcard" 
features. A '‘'?' with the high bit set (i.e., OBFH) will 
match any single character in the corresponding position. 
For example if NAME is two bytes long and is set to 41H, 
OBFH, the directory search routine will match Al, A2, AN, or 
any other segment whose name starts with A. A '*!' with the 
high bit set (i.e., OAAH) will match any string in the 
corresponding position. For example if NAME is two bytes 
long and is set to 41H, OAAH, the directory search routine 
will match on A, AA, Al, Al2, A123, AAASSSDDD, or any 
segment name beginning with 'A'. 


The matching of the tier level fields is done in the same 
Manner as the tier authorization match in the Adaptor. That 
is the two fields are ANDed together. If the result is non- 
zero then there is a match. 


50-90020490 Page 2 - 27 June 8, 1984 


Spec. 


DOS CALLS - DIRECTORY ROUTINES 


All values returned to the calling application are done so 
in the SEARCH BLOCK in the following manner: 

-If the search was successful the MATCH PATTERN is set 
to OFFH by the search routine. 

~If the search failed then the MATCH PATTERN is set to 
0 by the search routine. 

-If the search was successful, then the TYPE, OWNER, 
TIER LEVEL, SEGMENT ADDRESS, and NAME fields are filled 
in to correspond to the entry in the directory that was 
found. 


The following are a few examples of how the directory 
search routines work. 


yRead in a segment named BOMBAST 


? 
;Search the directory for the first entry with the name BOMBAST 


: 
' 


LD A,10H 

LD (MATCH_PATTERN) ,A ;Search for first occurrence. 
7Match on name. 

LD A,23 

LD (ENTRY_WIDTH) ,A 7Set entry width 


LD HL, SEGNAME 
LD DE, NAME 


LD BC,14 
LDIR 7Copy BOMBAST into NAME field. 
LD C,88H 


LD DE, SEARCH_BLOCK 


CALL 8 ;Call IOS to search the directory. 


LD A, (MATCH_PATTERN) 
A 


JP Z,NOT_FOUND ;Was search successful? 


;Search was successful. Read in segment. 
;Segment address is in SEG_ADDR 
CALL READSEG 
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7Read in second segment in directory which begins with the 
;letter 'A' and is owned by 69. This will require doing two 
;directory searches; one for the first occurence; and one 
;for the next occurence. 
LD A,12H 
LD (MATCH_PATTERN) ,A ;Find first occurence. Match on 
;NAME and OWNER. 


LD A,23 

LD (ENTRY_WIDTH) ,A ;Set ENTRY_WIDTH to 23 

LD A,'A' 

LD (NAME) ,A ;First character of NAME is 'A'. 
LD A,OAAH 

LD (NAME + 1),A ;Wildcard feature 

LD B,12 

LD Ay? 


LD HL,NAME + 2 


BLANK: LD (HL),A 


INC HL 

DJNZ BLANK 7Blank out remainder of NAME 
LD C,88H 

LD DE, SEARCH. BLOCK 

CALL 8 7Call directory search 


;Search for first is done. If successful then search for next. 
LD A, (MATCH_PATTERN) 
0 


CP 

JR Z,NOT_FOUND ;Was search successful 

LD A,92H 

LD (MATCH_PATTERN) ,A ;Search for next occurence of 


;NAME and OWNER 


LD A, OAAH 


LD (NAME + 1),A sWildcard feature 
LD B,12 
LD A,' ' 


LD HL,NAME + 2 
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BLANK1: LD (HL),;A 


INC HL 

DINZ BLANK 7Blank out remainder of NAME 
LD C,88H 

LD DE, SEARCH_BLOCK 

CALL 8 7Call directory search 


LD A, (MATCH_PATTERN) 
cP 0 

JR Z,NOT_FOUND 
;Read in the segment 
CALL READSEG 


SEARCH_BLOCK: 


MATCH_PATTERN: ps 1 
ENTRY_WIDTH: ps ol 
TYPE: ps 1 
OWNER: ps 1 
TIER_LEVEL: p 4 
SEG_ADDR: DS 3 
NAME: pS 14 
Spec. e900 204Gg °c Oe eee 
pec. 50-90020490 Page 2 - 30 


June 8, 1984 


DOS CALLS - INTERRUPTS AND TASKING 


4.2.3 The Interrupt Structure and Tasking Support 


4.2.3.1 Introduction 


Spec. 


Because of the Real-Time requirements of the NABU P.C., some 
sort of real time operating support is required. Because of 
the overhead involved in context switching and maintaining 
task descriptors and the questionable utility to 
applications programs, full multi-tasking is not supported. 
Instead, a modified forground/background tasking approach is 
used. The application program runs as the foreground task, 
and is in complete control of the NPC. The application 
program may also call I0S routines which run in the 
foreground, and may also start other tasks running in the 
background. The application program may also use _ I0S 
routines to start applications tasks running in the 
background. 


The background tasks are always started by the occurance of 
interrupts and must "run to completion". The NPC. supports 
eight vectored, maskable, nestable, priority interrupts. 
Each interrupt has an interrupt service routine or "system 
task" associated with it. Some of the interrupts may also 
have one or more “user tasks" associated with it. These 
"user tasks" will start after the system task for the given 
interrupt has completed. The NPC interrupts in order of 
priority are: 


1. NNI Receive 
-activated when a character is received from 
the NNI 
-system task for packet/segment reception 
handling attached to this interrupt 
-No user tasks may be attached 


2. NNI Send 
~activated when a character has been sent from 
the NPC to the NNI (Transmitter Buffer Empty) 
-System task for packet/segment reception handling 
attached to this interrupt 
~No user tasks may be attached 


3. Human Interface Input 
-activated when a character has been received 
from the remote keyboard 
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4. Video Frame Sync (60 Hz Clock) 

~activated every 1/60 sec by start of ; 
vertical retrace on the TMS 9918A Video Display 

-System task to: flash cursors, update real time 
clock, etc. etc attached to this interrupt ; 

-System task to timeout on NNI response attached to this 
interrupt 

-Any number of user tasks may be attached. 


5. Option Card Interrupt from Slot No. 0 
6. Option Card Interrupt from Slot No. 1 
7. Option Card Interrupt from Slot No. 2 
8. Option Card Interrupt from Slot No. 3 


Option Card Interrupts 
-activated by option cards 
-one syStem task per card may be attached 
as required 
-one user task per card may be attached 


4.2.3.2 Critical Regions 


Spec. 


For the purposes of the IOS, a critical region is defined as 
a section of executable code, or data structure which may be 
accessed by only one concurrently executing task at a time. 
Critical regions are bound to exist in any system which 
supports more than one concurrently executing task. 


Two IOS BOS calls are used to protect critical regions in 
the IOS and in applications programs. When entring a 
critical region, an application task must call the routine 
"CRITICAL_REGION_BEGIN". This is call number 02 in the IOS 
BOS and its assembly language name is CRBEG. It takes no 
parameters. When leaving the critical region the routine 
"CRITICAL_REGION_END" must be called. This is call number 03 
in the IOS BOS and its assembly language name is CREND. No 
registers are destroyed by these calls. 


Critical regions are nested by CRBEG and CREND. This nesting 
is analogous to opening a left bracket for each CRBEG that 
is performed and closing the critical region with a right 
bracket each time a CREND is performed. In this way it is 
easy to visualize that one may have a critical region within 
a critical region and that interrupts will only be enabled 
when the final right bracket (CREND) is reached. [It is also 
obvious that there must be as many CRENDs as there are 
CRBEGs in order to keep the interrupt control in order. 
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Since all interrupts are disabled inside critical regions, 
they MUST be kept as SHORT as possible. 


*** NOTE *** 


Attempting to interface with the segment handler while 
in a critical region, may yield unpredictable results. 
Avoid this situation. 

It is also strongly recommended that applications not 
use the EI and DI assembler instructions for critical 
region protection. Use the IOS CRBEG / CREND routines 
instead. (See BOS Calls.) 
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4.2.3.3 User Task Attachment Routines 


4.2.3.3.1 Attaching Tasks to the Clock 


An application program may attach tasks to the TMS-9918A VDP 
frame interrupt. As many tasks as desired may be attached. 
Tasks may be attached and removed from the clock by both the 
main application program and by other tasks. In fact a task 
may remove itself from the clock. It is also possible to have 
multiple invocations of the same piece of code as separate 
tasks. 


BEFORE CLOCK-ATTACHED TASKS ARE EXECUTED, ALL REGISTERS 
ARE SAVED, AND THEY ARE RESTORED AFTER THE COMPLETION OF 
THE TASK. 


A data structure called a TASK_CONTROL_BLOCK (TCB) is used 
to keep track of the relevent parameters of a task which is 
attached to the clock. The TCB has the following structure: 


VAR 
TASK_CONTROL_BLOCK: RECORD OF 
BEGIN 
NEXT_BLOCK : WORD 
RESET_INTERVAL : BYTE 
CURRENT_INTERVAL : BYTE 
TASK_ADDRESS : WORD 


[ PARAMETER_BLOCK USER_DEFINITION ] 
The NEXT_BLOCK word is used by the operating system to piace 
the TCB on a linked list with other TCB's. This word should 
not be altered by applications tasks at any time. 


The CURRENT_INTERVAL byte counts the number of ticks that 
have gone by since the last time the task was activated. It 
is accessed by the IOS but may also be accessed by 
applications tasks. The IOS algorithm in which this byte is 
used is as follows: 
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ON EACH CLOCK INTERRUPT DO 


BEGIN 
FOR EACH TASK_CONTROL-BLOCK DO 
BEGIN 
CURRENT_INTERVAL = CURRENT_INTERVAL —- 1; 
IF CURRENT_INTERVAL = 0 THEN DO 
BEGIN 
CURRENT_INTERVAL := RESET_INTERVAL; 
RUN_THIS_TASK( TASK_ADDRESS) ; 
END 
END 
END. 


The byte CURRENT_LINTERVAL is decremented every clock tick 
until it equals zero. When CURRENT_INTERVAL = 0, the task is 
executed. Therefore an INTITIAL DELAY may be issued before 
the task is dispatched by initializing CURRENT_INTERVAL to a 
value greater than one. Before execution of the task, 
CURRENT_INTERVAL is reset to the value of RESET_INTERVAL. 
CURRENT_INTERVAL is measured in clock ticks which are approx 
1/60 of a second long. For example a value of 5 means’ the 
task will every 5/60 of a second and a value of 1 means the 
task will run every 1/60 of a second or 16 milliseconds. 


NOTE: That initializing CURRENT_INTERVAL to zero will 
cause the task to be delayed for 256 clock ticks 
(approx 4 seconds) before it is executed a first 
time. 


The CURRENT_INTERVAL byte can be used to determine when a 
task has last run or when a task will next run. It will also 
determine when a newly created task will next run. 


The RESET_INTERVAL byte is the value to which the byte 
CURRENT_INTERVAL is initialized to after RESET_INTERVAL has 
been decremented to zero. This byte is never changed by the 
Operating system, but can be changed for purposes of 
changing the re-execution time of an active task. 


The TASK_ADDRESS word contains a pointer to the start of the 


task or user. subroutine. When control is given to the 
interrupt subroutine, the pointer to the TASK_CONTROL BLOCK 
(TCB) is in the BC register so that the user may access any 
of the bytes in the TCB and modify them if he so. desires. 
NOTE also that this pointer is useful for accessing vari- 


ables (bytes or words) immediatl belo t 
TASK_CONTROL_BLOCK. - i oat oe 
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Also note that an interrupt subroutine or task should always 
end with a RETURN (RET) statement in order to return control 
to the application's mainline and never jump out of a user 
task otherwise interrupts will remain permantly disabled. 
Interrupt subroutines should also always be as short as 
possible and never take longer than 16 milliseconds (1 CLOCK 
TICK) to execute. If it should be neccessary to run a_ task 
that takes longer than 16 miliseconds, it should be broken 
up into two tasks which execute on alternate interrupts. To 
do this start one task immediatly and delay the second 
task one clock tick by setting CURRENT_INTERVAL 
initially to two. 


The PARAMETER_BLOCK is an optional data structure which may 
be accessed by an applications task. When a task is started 
the address of the TASK_CONTROL_BLOCK (ie a pointer to the 
NEXT_BLOCK word) is passed in the BC Register. This gives 
the task access to its own TCB. Using the parameter block to 
keep all of the task's data will allow several 
instantiations of the same code as separate tasks without 
resorting to keeping data on stack frames. 


There are a few important calls which should be mentioned at 
this point, because tasks may not run if they are not done. 


A cakll must be done at the start of every program to link in 
the BOS routines so that calls to CRBEG and CREND will work. 
(See section on BOS Calls for information on linking BOS 
routines using DOS call 90H.) 


ex: 
MAIN: : 
LD C,90H #DOS CALL 90H 
LD DE,LNKTB## ;ADDRESS OF 
;LINK TABLE 
CALL DOS ;CALL SYSTEM 


A call must be done to CLKPRM (BOS CALL #37) should be done 
to enable user task dispatching when the user is ready to 
have the tasks dispatched. 


ex: LD C,4 7CONSIDER CLOCK 
?TASK 

;DISPATHING BIT 

LD E,4 7SET BIT #2 TO 


;TURN ENABLE 
;TASK DISPATCHING 

CALL CLKPRM## sNOW TASKS WILL 
;RUN IF INTERRUPTS 
;ARE ENABLED 


Spec. 50~-90020490 Page 2 - 36 June 8, 1984 


DOS CALLS - INTERRUPTS & TASKING - CLOCK 


NB: a cali to CLKPRM should be used instead of a call to 
CRBEG if the user wishes to disable ALL tasks for a long 
period of time. Because a call to CRBEG will disable ALL 
interrupts, and not only user tasks. 


The IOS DOS Routines which support attaching and removing 
clock tasks are as follows: 


CLOCK_USER_TASK_ATTACH (DOS call number 8BH) 
-used to attach a user task to the clock ISR 
-entry parameters: 
C Register: 8B Hex 
DE Register: Pointer to a Task Control Block 


CLOCK_USER_TASK_REMOVE (DOS call number 8CH) 
-used to remove a user task from the clock ISR 
~entry parameters: 
C Register: 8C Hex 
DE Register: Pointer to a Task Control Block 
If DE = 0, then all tasks are removed 


Note that although there is no limit to the number of tasks 
which may be attached to the clock, attaching too many 
tasks, or attaching long running tasks may cause clock 
interrupts to be lost. 
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EXAMPLE 


This routine demonstrates attaching and removing tasks. 


BOS EQU 0008 7 DOS ENTRY POINT 
COUNT: DB 0 ;Data byte incremented every 5/60 
3a second by interrupt subroutine 
; COUNTER 
CNTTCB: ; TASK_CONTROL_BLOCK 
DW O zpoint to next block = NIL 
DB O5 +RESET_INTERVAL 
DB 100 ;INITIAL_DELAY Of 100 ticks 
DW COUNTER ;Interrupt subroutine 
MAINLINE: : LD C,90H 7LINK_BOS_ROUTINE 


JP DRIVER zand do forever. 
COUNTER: sUSER'S INTERRUPT SUBROUTINE 
LD A, (COUNT) ;get current count 
INC A yincrement count 
LD (COUNT) /;A ;store new count 
RET yreturn to mainline. 
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7call number 


LD DE,LNKTB## ;address of user 


;LINKTABLE 
CALL DOS ;call location 8 
é 7SOME MORE MAINLINE CODE 
LD C,08BH 7C REG OQ8BH = CLOCK_USER_ATTACH. 
LD DE,CNTTCB ;DE REG = ADDRESS of TCB 
CALL DOS ;CALL location 8 to attach task 
7Now task is ATTACHED!! 
. ;MORE MAINLINE SETUP 
DRIVER: : ;MAINLINE DRIVER 
LD A, (COUNT) ;get count in A reg. 
CP 100 7Is count 100? 
JP NZ,DRIVER ;NO. Then wait till 
;COUNT = 100 
LD A,O ?YES. count = 100 so 
LD (COUNT),A zthen reset count to 0 
LD C,8CH 7;USER_TASK_REMOVE 
LD DE, CNTTCB 7TCB ADDRESS 
CALL DOS 7Now counting task will 


#no longer and the byte 
;COUNT will no longer be 
;incremented. 


4.2.3 
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-3.2 Keyboard User Tasks 


The IOS DOS call 95H will permit tasks to be attached to the 
keyboard. The user passes, in the DE registers, a pointer 
to a table whose format is as follows: 


| Number of | 


| Entries (Byte) ! J em ener em ene nse een n nnn 
athe anteater acta! I I Character Code (Byte) | 
[| ENTRY #1 | | ene eee eee een nnn 
el a ee | | SYM Key Qualifier (Byte) | 
| BNTRY #2 ee ee 
Seresa===s-s=-S- I | Pointer to I 
. ! | User Routine (Word) | 
‘ \ 0 eee een eee nen n een eee == 
| ENTRY #n ! 


The character code is the code sent by the keyboard. 
Joystick data is ignored. The SYM key qualifier indicates 
when the task is to be performed as follows: 


bit 0 = 0 then do not execute user routine when SYM 
key is down. 
0= 1 then execute user routine when SYM key is 
down. 
bit 1 = 0 then do not execute user routine when SYM 
key is up. 
ls 1 then execute user routine when SYM key is 
up. 


The user's routine must end with a RET to prevent disaster. 


If a user's routine is to be executed, then all normal 
processing of the key code received is superseded. This 
means the key will not be put in the queue and the PAUSE and 
TV/NABU keys will not be processed ~ only the user routine 
will be performed. A number of tasks may be attached to the 
same keyboard input code. This allows the application the 
option of having different tasks execute based on the 


condition of the SYM key qualifier for the same keyboard 
input code. 


Attaching a task to the SYM key may produce unusual results. 
This is due to the fact that the attached task will not 
allow the SYM key to execute in the proper manner. 
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WARNING - 


To remove 
keyboard, 


When attaching tasks to the keyboard that will 
attempt to write to the video control register 
ensure that no other foreground or background 
task is using the video routines FASTLD and 
FASTDU (and their 256 byte cousins) as they allow 
keyboard interrupts to occur. 


the keyboard task table in its entirety from the 
DOS call 95H is performed with the DE registers 


set to zero. 
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4.2.3.3.3 EXPANSION SLOTS 


Expansion slots in the NABU PC will be used to allow a number of 
different option cards to be added. There are four expansion 
slots in each PC. The option cards send an identification (id) 
code to a port at the option slot. The NABU PC picks up the ids 
by specifying the hex value COH for slot 0, DOH for slot 1, EOQH 
for slot 2, and FOH for slot 3. Since there can be so many 
different cards which can be installed in the NABU PC, and 
different configurations of these cards in the slots, it is not 
reasonable to include drivers for each option card in I0S. 


The solution is to have the application identify the cards 
installed in the expansion slots, and have interrupt service 
routines which will handle the option cards. 


To find out what is in the expansion card slots, a DOS call 94H, 
(GET_CONFIG) can be made. The input parameter is 94H passed in 
the C register. This call returns the address of the configura- 
tion block in registers HL. The format of the block is as fol- 
lows; 


CONFIGURATION BLOCK 

STRUCTURE ( IOS_VERSION_NO BYTE, 
IOS_LEVEL_NO BYTE, 
RESERVED WORD, 
SLOT_0_ CONTENTS BYTE, 
SLOT_1_CONTENTS BYTE, 
SLOT_2_CONTENTS BYTE, 
SLOT_3_CONTENTS BYTE ) 

END STRUCTURE 


An interrupt service routine can then be attached to an option 
slot interrupt letting the application deal with the option card 
directly. 


DOS call 8DH is the Slot Interru i i 
pt Service Rou 
entry parameters are: aa, i 


reg C: 8DH 
reg DE: pointer to ISR Control Block 
where the ISR Control Block contains 


byte 1 ~ slot number (C0,D0,E0, or FO cor- 
responding to slots 0,1,2 or 3) 
byte 2,3 - pointer to start of interrupt 


service routine. 


The address of the ISR i i i 
by the 10s. *S Placed into the interrupt vector table 
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Dos call 8EH is the Slot Interrupt Service Routine Remove. 
The parameters that must be passed to this routine are: 


Reg C = 8EH 
Reg E = Slot number (C0,D0,E0,FO corresponding to 
slots 0 to 3). 


This routine disables interrupts from the slot and then removes 
the address of the ISR from the interrupt vector table. 


The applications programmer must know the identification codes 
which are sent by the different option cards which the 
application will be using. The programmer must also initialize 
the interrupt hardware on the option card (if applicable). 


Spec. 50~90020490 Page 2 - 42 


DOS CALLS - HUMAN INPUT DEVICES 


4.2.4 HUMAN INPUT 


4.2.4.1 INTRODUCTION 


This section explains how keyboard and joystick data may be 
accessed through the I0S. 


4.2.5.2 SPECIAL KEY OPERATION 


beveral keyg have Special reserved functions and the 10S traps 
and handles these keys: 


EXIT OPERATION: 
PAUSE OPERATION: 
TV/NABU SWITCH: 
SYM OPERATION: 


The Exit Operation simply consists of jumping to location 0000H. 
This will cause a system re-boot to occur. (See also the section 
on XIOS.) 


The Pause operation stops the execution of the applications 
program. A LED on the NPC front pannel is turned on to indicate 
that the NPC is in Pause mode. While paused, only the SYM, EXIT, 
and PAUSE operations are interpreted. All other keys and human 
interface inputs are ignored. Pause mode is quit either by the 
reset operation or by another pause operation. 


The TV/NABU switch is used to switch between the external video 
input and the NPC generated video. When the NPC is booted NPC 
video is switched in. When the NPC is powered off, the hardware 
ensures that the external video is switched in. At any time when 
the NPC is operating the TV/NABU switch may be used to switch 
between computer generated and external video sources. 


For details as to what keycodes constitute the EXIT, PAUSE, 
TV/NABU and SYM operations, see TABLE l. 


The IOS handles all SYM key operation. See section 4.2.5.5 
for more information. 
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PUT CHARACTER CODE TABLE HERE 
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4.2.4.3 OBTAINING DATA FROM THE KEYBOARD 


The keyboard device driver has two entry points which are set up 
as standard serial device drivers. They are as follows: 


The routine "HUMAN_INPUT: DEVICE_READY" can be called to see if a 
particular keyboard device has data available. This call returns 
Q if nothing is ready and some non-zero value if there is a 
character ready. Note that the keyboard unit only sends joystick 
data if the value changes from the previous reading. Also, the 
keyboard unit "de-~bounces" digital joystick data. This means that 
if HUMAN_INPUT: DEVICE_LREADY returns TRUE for a particular joy- 
stick port, the value for that device is guaranteed to have 
changed. 


The parameter passing for the human interface is as follows: 


HUMAN_INPUT: DEVICE_READY (call number AQH) 
-returns a data ready indication for a specified human 
interface input 

-entry parameters: 

C Register: AQ Hex 

E Register: device location to be checked 
~returned value: 

A Register: 00 if device not ready 

non-zero value if device is ready 


HUMAN_INPUT: GET _DATA (call number A1H) 
-gets a data byte from a specified human interface input 
~see section 3.3.7.1 
-entry parameters: 

C Register: Al Hex 

E Register: device location to get data from 
-returned value: 

A Register: data input from human input device 
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Both routines pass the device location in the E register. The 
following device locations are defined: 


o0H -Reinitializes the keyboard device driver by 
making all devices "not ready" (throws away any 
ready data) (Works with DEVICE_READY only) 


O18. -Keyboard 

02H -Joystick l 

03H ~Joystick 2 

FFH ~returns the base address of the 


current SYM key re-definition 
table. (returns address in HL) 
(Works with DEVICE_READY only) 


The values returned from DOS call Al are either joystick data, 
or keyboard data. 


Joystick data uses the first five bits of the byte to 
determine the joystick's new change of direction. 


I | | girection 

| I | lef 

| 1 sake es down 

| : right 

up 

fire button 
not used 
not used 
not used 


Keyboard data is sent as single 8 bit bytes, usually in an ASCII 
format. There are however function keys which transmit special 
byte values. Table 1 should be consulted. 
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4.2.4.4 Set SYM Table 


The IOS performs all SYM key decoding. A 128 character look-up 
table, is maintained if it has been defined by an application 
program and passed to the IOS. Any key which is NOT release coded 
may have its meaning changed by holding down the SYM key while 
the key is pressed. A new key-code is chosen by doing a look-up 
in the re-definition lookup table. The resulting value is then 
passed on to the application program. If the SYM key is pressed 
when there is no defined redefinition table, then the ASCII value 
of the key pressed with the high bit set is passed on to the 
application program. 


SYM key re-definition is NOT performed on any key which is 
release coded. Release codes are sent onto the application by the 
device handler. It is up to the application to ignore them if 
they are not desired. 


The call SET_SYM_TABLE (call number 91H) is used to set the SYM 
redefinition table base address. The base address of the 
redefinition table is passed as a parameter. If the address 
passed is 0000H then any redefinition table currently in use is 
freed, and the new redefinition consists of setting the high bit 
in the ASCII code. The format of this call is as follows: 


SET_SYM_TABLE (call number 918) 
-used to set the SYM key Redefinition table 
-entry parameters: 
C Register: 91 Hex 
DE Register: Pointer to new SYM key table 
where the SYM KEY TABLE has the 
following format: 
128 Entries each one byte long 


Entry 0 contains the 
redefinition code of 
keyboard input code 0 when 
SYM key is down. The 


redefinition code is placed 
in the keyboard buffer or 


queue. 
Entry 1 contains the 
redefinition code of 


keyboard input code 1 when 
SYM key is down. 
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Entry 7FH contains the 
redefinition code of 
keyboard input code 1 when 
SYM key is down. } 


-returned value: 
HL Register: Old SYM key table 


The SYM Key Redefinition table is 128 bytes long. The 
contents of this table are used to redefine or 
translate the received ASCII character (values 0 to 
7FH) into a different ASCII character. For example, 
if the first entry inthe table is 7FH (delete 
character), and an ASCII 0 (ctrl @) is received, the 
CTRL @ will be replaced with the delete character. 
See TABLE 1 for the Keyboard ASCII Code Chart. 
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4.2.5 Video Screen Device Driver 


In keeping with the standard for physical device drivers, 


two entry points are provided for the Video Screen Device 
Drivers. These are as follows: 


VIDEO_SCREEN: DEVICE_READY (call number A2H) 
-returns a data ready indication for the video screen driver. 
-entry parameters: 
C Register: A2 Hex 
-returned value: 
A Register: 00 if device not ready 
non-zero value if device is ready 


VIDEO_SCREEN: SEND_DATA (call number A3H) 

-writes a character to the specified window 
-entry parameters 

C Register: A3 Hex 

D Register: data to be output 
-returned value: 

A Register: 00 if device not ready 

non-zero value if data was sent 


~It will handle control characters: carriage return, line 
feed, delete, backspace, form feed, and horizontal tabs. 
The routine puts the character at the current cursor 
position. Bit 7 is stripped off each ASCII character by 
"anding" with 7FH prior to displaying. It will interpret 
the control characters as follows: 


LINE FEED: CONTROL J 

If the cursor is on the bottom line of the window, the 
window will scroll up one line and leave the bottom 
line filled with SPACES and the cursor will drop 
straight down into this blank line. If the cursor is 
in the middle of the window, the cursor just drops 
down one line. 


CARRIAGE RETURN: CONTROL M 
The cursor will move to the first position of the 
current line. 


BACKSPACE: CONTROL H 


The cursor moves back one position. If the cursor is 
in the top-left position of the window, nothing 
happens. 
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DELETE: 7FH 
The cursor backspaces one character and places a SPACE 
over the character. 


FORM FEED: CONTROL L 
The cursor is reset to the top-left position of the 
window and the window is filled with SPACES. 


BELL: CONTROL G 
A short tone will sound. 


VERTICAL TAB: CONTROL K 
The cursor moves up one line. If the cursor is on the 
top-most line, nothing will happen. 


a 


HOME: CONTROL 
The cursor is reset to the top-left position of the 
window. 


OTHER CONTROL CHARACTERS: 
Nothing will happen. 
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4.2.6 Printer Output 


The printer output devices allow for data to be sent to a printer 
connected to the personal computer. There are two calls 
available. 


DOS call OA4H determines whether the printer is ready to receive 
data. A non zero value will be returned if the printer is not 
ready. 


DOS call OA5H will perform wait until the printer is ready and 
then send the data to the printer. The appropriate register 
values for the DOS calls A4 and AS are: 


PRINTER_OUTPUT: DEVICE_READY (call number A4H) 

~returns a printer ready indication 
-entry parameters: 

C Register: Ad Hex 

E Register: device location to be checked 
~returned value: 

A Register: 00 if device not ready 

non-zero value if device is ready 


PRINTER_OUTPUT: SEND_DATA (call number A5H) 
“writes a character to the printer 
“entry parameters: 
C Register: A5 Hex 
E Register: Device location where data is to be 
sent 
D Register: Data to be output 


EXAMPLE 


The following 280 assembler example demonstrates how to print a 
form feed on a printer. 


FF EQU oc 


START: LD C,0A4H ?PRINTER OUTPUT 
LD D, FF 7LOAD THE DATA TO BE DISPLAYED 
LD E,02H ;THE PRINTER IS DEVICE NUMBER 2 
CALL 0008 ;PRINT THE CHARACTER. IOS ENTRY 
RET 
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4.2.7 I/O ROUTER 


4.2.7.1 Physical Device Identification 


The physical devices are referred to by their physical 


location rather than their 


function. The following 


diagram indicates how a single byte is used to identify 


a physical device in the NPC: 


DEVICE_NUMBER 

indicates the particular device 
number at a device location. 
Device number 0 is reserved. 
Numbering should start at 1 

and increase sequentially. 

A particular device number 

can indicate either an input 

or an output device, but NOT 
both. 


DEVICE_LOCATION 

For x=0 

000 -at keyboard I/F 

001 -at TMS9918A 

010 -at Printer 

Oli -at Sound Generator 
100 -at NNI I/F 
For x=1 

000 -~at expansion slot 6 
001 -~at expansion slot 1 
010 -at expansion slot 2 
O11 -at expansion slot 3 


BOARD LOCATIONS 


IF x= 


0 -on processor board 
1 ~on expansion bus 


Physical devices are deemed by the NPC IOS to be one of two 
Sexes". These are serial-oriented and packet-oriented, 


Serial-oriented devices are dealt with 
é 1 one character at 
time. These are devices such as the TMS-9918A, the KEYBOARD 


and the PRINTER, 
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Packet oriented devices are dealt with a block of data at a 
time. Packets have a particular protocol associated with 
them and are generally associated with mass storage devices 
such as the NNI and floppy disks. 


4.2.7.2 Logical Device Identification 


The following logical devices are defined: 


KEYBOARD: (input portion of CONSOLE) 0 
SCREEN: (output portion of CONSOLE) 1 
LIST: (output) 2 
READER: (input device) 3 
PUNCH: (output device) 4 


4.2.7.3 I/O Routing Entry Point 


Assignments of physical devices to logical devices are 
performed by using the I/O Router Entry Point. This cali 
only allows serial-oriented physical devices to be attached 
to Logical devices. Mass=storage devices are handled 
through the Segment Loader Interface. The ATTACH entry point 
has the following format: 


I/O_ROUTER: ATTACH (call number 8AH) 


Spec. 


~attaches a particular physical device or mass storage 
file to a logical device 
-entry parameters: 
C Register: 8A Hex 
E Register: PHYSICAL:.DEVICE 
D Register: LOGICALZDEVICE 


Where LOGICAL:DEVICE is the byte value of a logical device 
as identified in the section above and PHYSICALZDEVICE is 
the byte value of a physical device, as identified above. 
This call will cause all subsequent I/O to the logical 


device to be performed by the physical device attached. This 
call is available in the DOS. 
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4.3 Basic Operating Software (BOS) 


This level of the operating system provides the key operating 
control software for the NABU P.C.. It interfaces to the I/0 
handlers, the Downloadable Operating Software and application 
programs. 


BOS Routines may be linked to the applications program at run 
time by using the IOS DOS call number 90H (LINK_BOS_ROUTINES). 


The application program is written with a jump table, with one 
entry in the table for each low level BOS routine accessed. Each 
entry is 3 bytes long. The exact structure is: 


TYPE 
ANENTRY: TYPE ARRAY([1..3] OF BYTE; 
VAR 
BOS_LINK_TABLE: RECORD OF 
LENGTH: BYTE; 
ENTRY[1..LENGTH] ANENTRY; 
END; 


The exact format of the IOS DOS call is: 


LINK_BOS_ROUTINES (call number 90H) 
~used to link BOS Routines to an 
application program 
-entry parameters: 
C Register: 90 Hex 
DE Register: Pointer to a BOS_LINK_TABLE 
-is not re-entrant 


The first byte of each entry contains the number of the BOS 
routine to be linked to. When the LINK_BOS_ROUTINES call is made, 
the IOS will go through the link table, placing the appropriate 
absolute jump instruction into each entry to link it to the 
desired routine. The application program can then jump directly 
through the link table to the desired routine. 


Example: 
Before DOS Call 90H | After DOS Call 908 
LNKTAB: DB 2 72 entries | DB 2 

DB 02H ;BOS Call - CRBEG {| JP 

DW 0 I <CRBEG> 

DB 03H ;BOS Call - CREND | JP 

DW 0 | <CREND> 
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The BOS routine numbers (HEX) are assigned as follows: 


00 VREGRD 
02 CRBEG 
04 VREGWR 
06 VNAMET 
08 VPTRNT 
OA VSPRST 
oc VBLKOF 
OE VRAMWR 
10 FASTLD 
L2 FASTDU 
14 VRAMLD 
16 VRAMDU 
18 SPMOVE 
1A SPNAME 
1¢ LPATRN 
1E VFILL 
20 PUTPAT 
22 SETMSG 
24 GETMSG 
26 VSETG1 
28 VSETSP 
2A - 34 Reserved 
36 AUDWR 
38 HOINT 
3A VMOVI 
3C FASTRD 
3E SETMK 


50-90020490 


Spec. 


01 VTABRD 
03 CREND 

05 VSTATR 
07 VCOLRT 
09 VSATRT 
OB VBLKON 
oD VRAMRD 
OF FASTL8 
U1, FASTD8 
13 VRAML8 
15 VRAMD8 
17 SPMARK 
19 SPCOLR 
1B RPATRN 
1D CHADR 

IF XYLOC 

21 GETPAT 
23 PUTMSG 
25 VSETTX 
27 VSETG2 
29 MUL88 

35 AUDRD 

37 CLKPR 

39 CREGW 

3B VMOVD 

3D FASTWR 
Page 3 ~- 2 
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The BOS calls use several dedicated data structures. They are 
defined as follows and are referred to in the specific BOS 
routines. 


The MESSAGE_CONTROL_BLOCK consists of : 


X LOCATION on screen (byte) 
Y LOCATION on screeen (byte) 
LENGTH OF MESSAGE (byte) 
DATA TO BE WRITTEN (byte(s) ) 


The PATTERN_DEFINITION_TABLE consists of: 


# OF ENTRIES IN TABLE 31 BYTE 
BLOCK 1 ;character 1 
BLOCK 2 scharacter 2 
BLOCK N z;character N 
EACH BLOCK CONTAINS: 
# OF PATTERN 31 BYTE 
PATTERN DEF. 78 BYTES WICH REPRESENT THE DEFINITION. 
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ROUTINE NAME: AUDRD 


FUNCTION: 
Read the audio chip 


DESCRIPTION: 
This routine reads from the GI complex sound generator. 
The register to be read is passed in C and the data is 
returned in A 


PARAMETERS PASSED: 
C Reg: Number of sound register to be read 


PARAMETERS RETURNED: 
A Reg: Value of sound register read 


REGISTERS USED: 
Flags, A, C 
2 Bytes of stack used 


ROUTINE TYPE GLOBAL - BOS No. 35 - Re-entrant 


COMMENTS AND WARNINGS: 
This call can be used by the application program to read 
the current status of the audio chip's registers. There 
are fourteen audio registers uses by the application. For 
more information on the audio chip, see Section 3.3. 


RELATED ROUTINES: 
AUDWR - write to the audio chip 
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ROUTINE NAME: AUDWR 


FUNCTION: 
Write to the audio chip 


DESCRIPTION: 
This routine writes to the GI complex sound generator used 
by the NABU PC. The register to be written to is passed in 
C and the data to be written is passed in E. The routine 
prevents writes to registers OE or OF. 


PARAMETERS PASSED: 
C Reg: Number of sound register to be written to 
E Reg: Data to be written 


PARAMETERS RETURNED: 
NONE 


REGISTERS CLOBBERED: 
A, C, E, Flags 
2 Bytes of stack used 


ROUTINE TYPE GLOBAL ~ BOS No. 36 - Re~entrant 


COMMENTS AND WARNINGS: 
This routine writes to a specified register within the 
audio chip. Fourteen registers are used for sound 
generator. For more information on programming sound see 
section 3.3. 


RELATED ROUTINES: 
AUDRD ~ read from the audio chip 
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ROUTINE NAME: CHADR 


FUNCTION: 
Return VRAM address for a particular pattern 


DESCRIPTION: 


This routine will return the VRAM address for a particular 
pattern in a pattern table. The pattern number is passed 
in the C register, the address returned in the HL pair. 


The base address of the pattern table is passed in DE. 


PARAMETERS PASSED: 
C = pattern number 
DE = base address of PATTERN_DEF_TAB 


PARAMETERS RETURNED: 
HL = address of pattern 


REGISTERS USED: 
BC, HL 
Stack use = 2 bytes 


ROUTINE TYPE GLOBAL - BOS No. 1D - Re~entrant 


COMMENTS AND WARNINGS: 
This routine allows the application to obtain the exact 
address in Video RAM (VRAM), where a given character 
resides. It is assumed that the pattern table has 
already been defined and the base address is known by the 


application. 
RELATED ROUTINES: 
VPTRNT - set pattern table base address 
VRAMLD - load Video RAM 
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@ ROUTINE NAME: CLKPR 


FUNCTION: 
Change processing of real time clock functions 


DESCRIPTION: 
This routine is used to control processing of real time 
functions. Three functions may be controlled - clock user 


task handling, screen driver cursor flashing and real time 
clock updating. 


These functions may be turned on or off at will by the 
applications program. This might be done to get more 
processor resources, or to get special control of these 
functions. Each function is controlled by a bit in a 
control word as shown below: 


--- Real Time Clock 
ge Cursor Flashing 


ae aa aioe as Clock Task Dispatching 


FHSS Snes SSeS = Not Used 


PARAMETERS PASSED: 
E Reg: Data to indicate state to set 
1 = process 0 = turn off 
C Reg: Mask Data. Bits in E which are to actually 
be considered are set in the mask. 


PARAMETERS RETURNED: 
A Reg: New value of control word 


REGISTERS USED: 
A, C, Flags 
4 Bytes of stack used 
ROUTINE TYPE GLOBAL - BOS No. 37 ~ Re~entrant 


COMMENTS AND WARNINGS: 
Of course altering real time processing can cause problems. 
Use with caution! 
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ROUTINE NAME: CRBEG 


FUNCTION: 
Critical region begins (disable interrupts) 


DESCRIPTION: 

This routine is used to delineate the beginning of a 
"critical region". A critical region is any section of code 
which, because it uses software timing, accesses data used 
by another task, or is not reentrant and can be called by 
more than one task, must run with interrupts disabled. Note 
that critical regions must be made as short as possible, or 
keyboard strokes and clock ticks may be lost. 


PARAMETERS PASSED: 
None 


PARAMETERS RETURNED: 
None 


REGISTERS USED: 
None 
2 Bytes of stack used 


ROUTINE TYPE GLOBAL - BOS No. 2 - Re-entrant 
COMMENTS AND WARNINGS: 


All interrupts are disabled by this call. Long critical 
regions may result in loss of clock ticks or keyboard 


data. 
NOTE: 1. critical regions may be nested safely about 100 
deep. 
2. the number of CRENDs must match the number of 
CRBEG's 


RELATED ROUTINES: 
CREND - critical region ends 
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ROUTINE NAME: CREGW 


FUNCTION: 
Write to the hardware control register 


DESCRIPTION: 
This routine is used to write the control register port in 
the NABU P.C. The control register port is a write-only 
register with the following format: 


! 1 | | I I 

I I | | I | I --- ROM Select 

! 1 I I r | | 

I I | 1 | i tateteteteted Video Switch 

| I | I | I 

| | | | [0 ween enn Data Strobe (printer) 

{ 1 | ! I 

! I | | wee mee nenennnna- Green Front Panel LED (Check) 
! |  testetetetetatetetetntetetetatatetetes Red Front Panel LED (Alert) 
rrr nnn nnn ne Yellow Front Panel LED (Pause) 
ites estentesttetesheteteatetatetettneteteteteten NOT USED 

{ 

SRS SRS SS SSS eae es Se re eee NOT USED 


PARAMETERS PASSED: 
E Reg: Data to be Written to Port 
C Reg: Mask Data. Bits in E which are to actually 
be written are set in the mask. 


PARAMETERS RETURNED: 
A Reg: New value of control register 


REGISTERS USED: 
A, C, Flags 
4 Bytes of stack used 


ROUTINE TYPE GLOBAL - BOS No. 39 - Re-entrant 


COMMENTS AND WARNINGS: 
Altering anything other than the Video Switch and the yellow 
and green alerting LED may cause a small disaster. Use with 
care, 
Toggling the Video switch allows the application to switch 
the signal to the T.V. from the television broadcast to the 
video chip output and back again. 
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ROUTINE NAME: CREND 


FUNCTION: 
Critical region ends 


DESCRIPTION: 

This routine is used to delineate the end of a "critical 
region". A critical region is any section of code which, 
because it uses software timing, accesses data used by 
another task, or is not reentrant and can be called by more 
than one task, must run with interrupts disabled. Note that 
critical regions must be made as short as possible, or 
keyboard strokes and clock ticks etc. may be lost. A CREND 
must be used to end a critical region started by a CRBEG. 


PARAMETERS PASSED: 
None 


PARAMETERS RETURNED: 
None 


REGISTERS USED: 
None 
2 Bytes of stack used 


ROUTINE TYPE GLOBAL - BOS No. 3 ~- Re-entrant 
COMMENTS AND WARNINGS: 
See "Critical Regions" in the section "DOS Calls - 
Interrupts and Tasking." 


NOTE l. critical regions may safely be nested 100 


deep. 
2. the number of CREND's must match the number of 
CRBEG's. 
RELATED ROUTINES: 
CRBEG - critical region begins 
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ROUTINE NAME: FASTD8 


FUNCTION: 


Read a string of bytes from the VRAM. 


DESCRIPTION: 


This routine is used to read a string of bytes from the 
VRAM. The length of the data to be read is passed in reg 
BC and the memory address where the data is to be placed 
is passed in reg DE. The start address in VRAM is passed 
in HL. Since 16 bit pointers are used, anywhere from 0 to 
16K of data may be transfered with this routine. The 
entry point FASTD8 may be used if the length of data is 
less than 256 bytes and the length is passed in the C reg 
only. This routine keeps interrupts (except keyboard 
interrupts) disabled for the duration of the VRAM dump. 
This makes the dump very fast, but susceptable to loss of 
clock ticks or other interrupts. 


PARAMETERS PASSED: 


C Reg: Length of data block to be read 


DE Reg: Start of area to dump to in RAM 
HL Reg: Start of source area in VRAM 


PARAMETERS RETURNED: 


NONE 


REGISTERS USED: 


A, BC, DE, HL, Flags 
6 Bytes of Stack Used 


ROUTINE TYPE GLOBAL - BOS No. 11 - Re~entrant 


COMMENTS AND WARNINGS: 


This routine keeps interrupts (except keyboard interrupts) 
disabled for a long period of time. Interrupts may be 
lost! 


RELATED ROUTINES: 


Spec. 


FASTDU - fast dump 

VRAMD8 - dump Video RAM (up to 256 bytes) 

VRAMDU - dump Video RAM 
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ROUTINE NAME: FASTDU 


FUNCTION: 
Read a string of bytes from the VRAM. 


DESCRIPTION: 

This routine is used to read a string of bytes from the 
VRAM. The length of the data to be read is passed in reg 
BC and the memory address where the data is to be placed 
is passed in reg DE. The start address in VRAM is passed 
in HL. Since 16 bit pointers are used, anywhere from 0 to 
16K of data may be transfered with this routine. This 
routine keeps interrupts (except keyboard interrupts) 
disabled for the duration of the VRAM dump. This makes the 
dump very fast, but susceptable to loss of clock ticks or 
other interrupts. 


PARAMETERS PASSED: 
BC Reg: Length of data block to be read 
DE Reg: Start of area to dump to in RAM 
HL Reg: Start of source area in VRAM 


PARAMETERS RETURNED: 
NONE 


REGISTERS USED: 
A, BC, DE, HL, Flags 
6 Bytes of Stack Used 


ROUTINE TYPE GLOBAL - BOS No. 12 - Re-entrant 
COMMENTS AND WARNINGS: 
This routine keeps interrupts (except keyboard interrupts) 


disabled for a long period of time. Interrupts may be 
lost! 


This will affect tasks attached to the clock, and software 
timing if a very large number of bytes are being read. 


RELATED ROUTINES: 


FASTD8 ~ fast dump (less than 256 bytes) 
VRAMD8& - Video RAM dump (less than 256 bytes) 
VRAMDU - Video RAM dump 
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ROUTINE NAME: FASTL8 


FUNCTION: 


write a string of bytes to the VRAM. 


DESCRIPTION: 


This routine is used to write a string of bytes to the 
VRAM. The length of the data to be written is passed in 
reg BC and the memory address of the start of the data is 
passed in reg DE. The start address in VRAM is passed in 
HL. Since 16 bit pointers are used, anywhere from 0 to 16K 
of data may be transfered with this routine. The entry 
point FASTL8 may be used if the length of data is less 
than 256 bytes and the length is passed in the C reg only. 
This routine keeps interrupts (except keyboard interrupts) 
disabled for the duration of the VRAM load. This makes 
the load very fast, but susceptable to the loss of clock 
ticks or other interrupts. 


PARAMETERS PASSED: 


C Reg: Length of data block to be written 
DE Reg: Start address of data block in RAM 
HL Reg: Destination of data in VRAM 


PARAMETERS RETURNED: 


NONE 


REGISTERS USED: 


A, BC, DE, HL, Flags 
6 Bytes of Stack Used 


ROUTINE TYPE GLOBAL - BOS No. OF - Re-entrant 


COMMENTS AND WARNINGS: 


This routine keeps interrupts (except keyboard inter 
rupts) disabled for a long period of time. Interrupts may 
be lost! 


RELATED ROUTINES: 


FASTLD - fast load 
VRAML8 ~ load Video RAM (up to 256 bytes) 
VRAMLD - load Video RAM 
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ROUTINE NAME: FASTLD 


FUNCTION: 
Write a string of bytes to the VRAM. 


DESCRIPTION: 

This routine is used to write a string of bytes to the 
VRAM. The length of the data to be written is passed in 
reg BC and the memory address of the start of the data is 
passed in reg DE. The start address in VRAM is passed in 
HL. Since 16 bit pointers are used, anywhere from 0 to 16K 
of data may be transfered with this routine. This routine 
keeps interrupts (except keyboard interrupts) disabled for 
the duration of the VRAM load. This makes the load very 
fast, but susceptable to the loss of clock ticks or other 
interrupts. 


PARAMETERS PASSED: 
BC Reg: Length of data block to be written 
DE Reg: Start address of data block in RAM 
HL Reg: Destination of data in VRAM 


PARAMETERS RETURNED: 
NONE 


REGISTERS USED: 
A, BC, DE, HL, Flags 
6 Bytes of Stack Used 


ROUTINE TYPE GLOBAL - BOS No. 10 - Re~entrant 


COMMENTS AND WARNINGS: 
This routine keeps interrupts (except keyboard inter 
rupts) disabled for a long period of time. Interrupts may 
be lost! 


This will affect tasks attached to the clock, and software 
timing if a large number of bytes are being read. 


RELATED ROUTINES: 


FASTL8 ~ fast load (less than 256 bytes) 
VRAML8 - load Video RAM (less than 256 bytes) 
VRAMLD ~- load Video RAM 
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ROUTINE NAME: ASTRD 


FUNCTION: 
Read a single byte of data from TMS9918A VRAM - unprotected 


DESCRIPTION: 
This routine is used to read a single byte of data from 
TMS9918A VRAM. The address to be read is passed in reg BC, 
the value of the VRAM at that location is returned in reg A. 
This routine is not protected using the CRBEG and CREND 
routines. 


PARAMETERS PASSED: 
BC Reg: Location of VRAM to be read from 


PARAMETERS RETURNED: 
A Reg: Contents of VRAM at Location 


REGISTERS USED: 
A,F 
4 bytes of stack used 
ROUTINE TYPE GLOBAL - BOS No. 3C ~ Re-entrant 


COMMENTS AND WARNINGS: 
USE AT YOUR OWN RISK!! 


RELATED ROUTINES: 


FASTWR - fast write of one byte to Video RAM 
VRAMRD - read one byte from Video RAM 
VRAMWR - write one byte to Video RAM 
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ROUTINE NAME: FASTWR 


FUNCTION: 
Write a Single byte of data to TMS9918A VRAM ~ unprotected 


DESCRIPTION: 
: This routine is used to write a single byte of data from 
TMS9918A VRAM The address to be written is passed in reg BC. 
The data to be written is passed in Register E. This 
routine is not protected using the usual CRBEG and CREND. 


PARAMETERS PASSED: 
BC Reg: Location of VRAM to be written to 
E Reg: Data to be written 


PARAMETERS RETURNED: 
NONE 


REGISTERS USED: 
A, BC, flags 
4 bytes of stack used 
ROUTINE TYPE GLOBAL - BOS No. 3D - Re~entrant 


COMMENTS AND WARNINGS: 
USE AT YOUR OWN RISK!1 


RELATED ROUTINES: 


FASTRD - fast read of one byte of Video RAM 
VRAMRD - read one byte from Video RAM 
VRAMWR - write one byte to Video RAM 
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ROUTINE NAME: GETMSG 


FUNCTION: 
Get message from screen 


DESCRIPTION: 


GETMSG gets a string of patterns from the 


PARAMETERS PASSED: 
BC = pointer to message control block 


PARAMETERS RETURNED: 
None 


REGISTERS USED: 
A,B,C,D,E,F,H,L 
2+ Bytes of stack used 


ROUTINE TYPE GLOBAL ~- BOS No. 24 - Re-entrant 


COMMENTS AND WARNINGS: 
The message control block is set up 
application program. 


RELATED ROUTINES: 
PUTMSG - put message on the screen 


in 


screen. 
pointer to a MESSAGE_CONTROL_BLOCK is passed in reg BC. 


A 


RAM by the 
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ROUTINE NAME: GETPAT 


FUNCTION: 
Get pattern number for any X-Y location on screen 


DESCRIPTION: 
GETPAT gets a pattern number from a specific X-Y location 
on the screen. The pattern number is returned in the A 
register, the X location passed in the C register, and the 
Y location passed in the E register. 


PARAMETERS PASSED: 
C = X location 
E = Y location 
PARAMETERS RETURNED: 

A = pattern number 


REGISTERS USED: 
A,BC,DE,HL 
Stack use = 6 bytes 


ROUTINE TYPE GLOBAL — BOS No. 21 - Re-entrant 

COMMENTS AND WARNINGS: 
NOTE: The screen must be set up already. iee. pattern 
table, sprite tables, colour table, and attribute table. 


RELATED ROUTINES: 
PUTPAT - put a pattern on the screen. 
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ROUTINE NAME: HOINT 


DESCRIPTION: 
Initializes systems on the NABU PC, Calls all initializa~ 
tion routines for all devices and drivers, sets the control 
register of the NABU PC, and initializes the interrupt 
mask. 


PARAMETERS PASSED: None. 

PARAMETERS RETURNED: None. 

REGISTERS CLOBBERED: ALL 

ROUTINE TYPE GLOBAL - BOS No. 38 ~ Re~entrant 
COMMENTS AND WARNINGS: 


This routine is not usually needed by an application 
program. 
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ROUTINE NAME: LPATRN 


FUNCTION: 


Load pattern definitions into VRAM memory 


DESCRIPTION: 


LPATRN loads pattern definitions into a VRAM pattern table. 
The patterns to be loaded are put into a 
PATTERN_DEFINITION_TABLE, which is described below. A 
pointer to the PATTERN_DEFINITION_TABLE is passed in the BC 
register. The base address of the pattern table is passed 
in DE. 


PARAMETERS PASSED: 


BC = pointer to PATTERN_DEF_TAB 
DE = Base address of table 


REGISTERS USED: 


A,B,C,D,E,F,H,L 
2 Bytes of stack used 


ROUTINE TYPE GLOBAL ~ BOS No. 1C - Re~entrant 


COMMENTS AND WARNINGS: 


This routine can be used to load pattern definitions from 
RAM into Video RAM (VRAM). The base address of the table 
in VRAM to which the pattern definitions are going must 
already be established i.e. base address set. The 

pattern table, sprite definition table, and the colour 
table can be loaded with this routine. 


RELATED ROUTINES: 


Spec. 


RPATRN - load pattern definitions for pattern table 


50-90020490 Page 3 - 20 June 8, 1984 


BOS CALLS 


ROUTINE NAME: MUL88 


FUNCTION: 
Multiply two eight bit numbers 


DESCRIPTION: 
MUL88 multiplies two 8 bit numbers together to yield a 16 
bit result. The numbers to be multiplied are passed in the 
C and E registers, the answer is returned in both HL and BC 


PARAMETERS PASSED: 
Cc = multiplicand 
E = multiplier 


PARAMETERS RETURNED: 
BC = result 
HL = result 


REGISTERS USED: 
BC,DE,HL 
Stack use = 0 
ROUTINE TYPE GLOBAL ~- BOS No. 29 - Re-entrant 


COMMENTS AND WARNINGS: 
None 


Spec. 50-90020490 Page 3 - 21 June 8, 1984 


BOS CALLS 


ROUTINE NAME: PUTMSG 


FUNCTION: 
Put message on screen 


DESCRIPTION: 
PUTMSG places text on the screen. A pointer to a 
MESSAGE_CONTROL_BLOCK is passed in the BC registers. 


PARAMETERS PASSED: 
BC = pointer to message control block 


PARAMETERS RETURNED: 
None 


REGISTERS USED: 
A,B,C,D,E,F,H,L 
2+ Bytes of stack used 


ROUTINE TYPE GLOBAL ~ BOS No. 23 - Re~entrant 

COMMENTS AND WARNINGS: 
This routine assumes that a graphics or text mode, and 
pattern tables are defined. It also assumes that the 
pattern table loaded in Video RAM has an ASCII character 
set loaded into the appropriate locations within the 
pattern table. 


RELATED ROUTINES: 
GETMSG ~ get a message from the screen 
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ROUTINE NAME: PUTPAT 


FUNCTION: 
Put pattern at any X-Y location on screen 

DESCRIPTION: oer — 
PUTPAT places any pattern definition at a specific X-¥ 
location on the screen. The pattern number is passed in L 


register, the xX location in the C register, and the Y 
location in the E register. 


PARAMETERS PASSED: 


C = X location on screen 
E = Y location 
L = pattern number 


PARAMETERS RETURNED: 
None 


REGISTERS USED: 
BC, DE, HL 
Stack use = 6 bytes 
ROUTINE TYPE GLOBAL ~ BOS No. 20 - Re-entrant 


COMMENTS AND WARNINGS: 


The graphics or text mode must already be defined before 
this routine is called. The pattern tables must also be 
set up (base addresses set, and pattern definitions 


loaded). 
RELATED ROUTINES: 
GETPAT - get pattern number for an X-Y screen 
location 
Spec, 50-9002 (40g Eee eee To eee 
0490 Page 3-930 Tore 


June 8, 1984 


BOS CALLS 


ROUTINE NAME: RPATRN 


FUNCTION: 
Load pattern definitions into screen pattern table 


DESCRIPTION: 
RPATRN loads pattern definitions into the screen's pattern 
table. A pointer to a PATTERN_DEFINITION_TABLE is passed 
in register BC. The PATTERN_TABLE address is assumed to be 
at VPTRNAD. 


PARAMETERS PASSED: 
BC reg = pointer to PATTERN_DEF_TAB 


PARAMETERS RETURNED: 
None 


REGISTERS USED: 
A,B,C,D,E,F,H,L 
2+ Bytes of stack used 


ROUTINE TYPE GLOBAL - BOS No. 1B - Re-entrant 


COMMENTS AND WARNINGS: 
It is assumed the base address of the pattern table 
(VPTRNAD) has already been set. 
VPTRNAD is defined and set using BOS routine VPTRNST. 


RELATED ROUTINES: 
LPATRN ~ load pattern definitions into Video RAM 


Spec. 50-90020490 Page 3 - 24 June 8, 1984 


BOS CALLS 


ROUTINE NAME: SETMSG 


FUNCTION: 
Set up screen message 


DESCRIPTION: 
SETMSG sets up the VDP and all parameters according to 
MESSAGE_CONTROL_BLOCK. The user may then load or dump to 
VRAM, and the patterns will be placed appropriately. The 
pointer to the message control block is passed in the BC 
register pair. The user should use VRAML8 or VRAMD8 
immediatley after this. 


THE A REGISTER CONTAINS THE TYPE OF SETMSG. 0 
1 


FOR READ 
FOR WRITE 


PARAMETERS PASSED: 
BC = pointer to MESSAGE_CONTROL_BLOCK 


PARAMETERS RETURNED: 
C = Length of message 
DE = Pointer to data to be read/displayed. 
HL = VRAM address to read/write. 


REGISTERS USED: 
A, BC,DE,HL 
Stack use = 6 bytes 
ROUTINE TYPE GLOBAL —- BOS No. 22 ~ Re-entrant 
COMMENTS AND WARNINGS: 
The routine PUTMSG is made up of SETMSG and VRAML8. SETMSG 
should be used by the application program for dumping VRAM 
contents into RAM. 


RELATED ROUTINES: 


PUTMSG - put message on the screen 
VRAML8 - load up to 256 bytes into Video RAM 
VRAMD8 - dump up to 256 bytes into RAM 


Spec. 50-90020490 Page 3 - 25 June 8, 1984 


BOS CALLS 


ROUTINE NAME: SETMSK @ 


FUNCTION: 
Write hardware interrupt control register and mask. 


DESCRIPTION: 
This routine is used to write or set the interrupt control 


register port in the NABU PC. The control register is a 
write-only register with the following bit format: 


I --- Slot 4 Interrupt 
| 
Ss TSa-= Slot 3 Interrupt 
Srassssrcee Slot 2 Interrupt 
StensesssasssS Slot 1 Interrupt 
hace a al Clock Interrupt 
worn nn nnn nnn nnn Keyboard Interrupt @ 
tr nr nnn nn nnn enn nn Adaptor Tx Interrupt 
aati aah aieareneeieaheaded eaten tetera Adaptor Rx Interrupt 
PARAMETERS PASSED: 
E Reg: Data to be written to the port. 
C Reg: Mask Data. Bits in E that are to actually 
be written are set in the mask. 


PARAMETERS RETURNED: 
A Reg: Previous value of the control register. 


REGISTERS USED: 

A, C, Flags 

4+ Bytes of stack used 
ROUTINE TYPE GLOBAL - BOS No. 3EH - Non Re~entrant 
COMMENTS AND WARNINGS: 


The implications of playing with the interrupt control 
register are considerable. Use with caution. 
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BOS CALLS 


ROUTINE NAME: SPCOLR 


FUNCTION: 
Set the colour of a sprite. 


DESCRIPTION: 
This routine is used to set the colour of a sprite. The 
sprite number is passed in register C and the new sprite 
colour is passed in register E. 


PARAMETERS PASSED: 
C Reg: Number of sprite to change colour of 
E Reg: Number of new colour 


PARAMETERS RETURNED: 
NONE 


REGISTERS USED: 
A, BC, DE, HL, Flags 
6 bytes of stack used 
ROUTINE TYPE GLOBAL - BOS No. 19 - Re-entrant 
COMMENTS AND WARNINGS: 
NOTE that the colour, the sprite location (SPMOVE) and 
the sprite pattern (SPNAME) must all be called before a 
sprite appears on the screen. 


RELATED ROUTINES: 


SPMOVE - move sprite 
SPNAME - assign pattern definition to sprite 
SPMARK - mark last sprite 
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BOS CALLS 


ROUTINE NAME: SPMARK 


FUNCTION: 
Mark the end of a sprite attribute table 


DESCRIPTION: . 
This routine is used to mark the end of a sprite attribute 
table. The number of the sprite to be marked (ie. the 
sprite AFTER the last sprite) is passed in the C register. 


PARAMETERS PASSED: 
C Reg: Number of sprite to be marked 


PARAMETERS RETURNED: 
NONE 


REGISTERS USED: 

A, BC, DE, HL, Flags 

6 Bytes of stack used 
ROUTINE TYPE GLOBAL ~ BOS No. 17 - Re~entrant 
COMMENTS AND WARNINGS: 


NOTE: If a sprite pattern is defined on the sprite number 
that was marked by this routine, the sprite mark is 
effectively removed. 


RELATED ROUTINES: 


SPMOVE - move sprite 
SPCOLR - set sprite colour 
SPNAME - assign pattern definition to sprite 
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BOS CALLS 


ROUTINE NAME: SPMOVE 


FUNCTION: 
Move a sprite on the display. 


DESCRIPTION: 
This routine is used to move a sprite on the display. The 
new X location is passed in L, the new Y location is passed 
in E and the number of the sprite to be moved is passed in 
register C. 


PARAMETERS PASSED: 
C Reg: Number of sprite to be moved 
E Reg: New Y location 
L Reg: New X location 


PARAMETERS RETURNED: 
NONE 


REGISTERS USED: 
A, BC, DE, HL, Flags 
6 Bytes of stack used 


ROUTINE TYPE GLOBAL - BOS No. 18 —- Re-entrant 


COMMENTS AND WARNINGS: 
This routine is also used to define the first location of 
a sprite. 
NOTE: The colour, and pattern must also be defined to 
have the sprite appear on the screen. 


RELATED ROUTINES: 


SPMARK - mark the last sprite being used 
SPCOLR ~ set sprite colour 
SPNAME - set sprite pattern definition 
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BOS CALLS 


ROUTINE NAME: SPNAME 8 


FUNCTION: 
Set the pattern name associated with a sprite. 


DESCRIPTION: 
This routine is used to set the pattern name associated 
with a sprite. The sprite number is passed in register C 
and the new sprite pattern name is passed in register E. 


PARAMETERS PASSED: 


C Reg: Number of sprite to change pattern of 
E Reg: Number of new pattern 


PARAMETERS RETURNED: 
NONE 


REGISTERS USED: 
A, BC, DE, HL, Flags 
6 bytes of stack used 


ROUTINE TYPE GLOBAL - BOS No. 1A - Re-entrant 


COMMENTS AND WARNINGS: 
NOTE: 1. The pattern name is the pattern which resides in @ 
the sprite pattern table in Video RAM. 
2. The colour and the location of the sprite must 
be defined before the sprite will appear on the 
screen. 


RELATED ROUTINES: 
SPMARK - mark the last sprite being used 
SPCOLR - set the colour of the sprite 
SPMOVE - set the location of the sprite 
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BOS CALLS 


ROUTINE NAME: VBLKOF 


FUNCTION: 
Unblanks (turns on) the TMS9918A video display. 
DESCRIPTION: 
This routine unblanks (turns on) the TMS9918A video 
display. It requires no parameters. 
PARAMETERS PASSED: 
None 
PARAMETERS RETURNED: 
None 
REGISTERS USED: 
A, BC, E, HL, Flags 
4 bytes of stack used 
ROUTINE TYPE GLOBAL ~ BOS No. OC — Re~entrant 
COMMENTS AND WARNINGS: 
The definition of the screen, i.e. mode, patterns etc, 
should be done before unblanking the screen. When a mode 
is selected be it TEXT, GRAPHICS 1, or GRAPHICS 2, the 


screen is "blanked" and remains blank until the VBLKOF 


routine "unblanks” it. 


RELATED ROUTINES: 


VBLKON - blank the video display 
VSETTX - set to TEXT mode 

VSETG1 - set to GRAPHICS 1 mode 
VSETG2 - set to GRAPHICS 2 mode 
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BOS CALLS 


ROUTINE NAME: VBLKON 


FUNCTION: 
Blanks the TMS9918A video display. 


DESCRIPTION: 
This routine blanks the TMS9918A video display. It requires 
no parameters. Blanking means all foreground colours and 
Sprites disappear from the screen. The background colour 
remains. 


PARAMETERS PASSED: 
None 


PARAMETERS RETURNED: 
None 


REGISTERS USED: 
A, BC, E, HL, Flags 
4 bytes of stack used 


ROUTINE TYPE GLOBAL - BOS No. OB — Re-entrant 


COMMENTS AND WARNINGS: 
NOTE: The TV screen goes blank on calling this routine, e 
but the definitions that have been set up in Video RAM 
remain. To regain the image on the screen, use VBLKOF. 


RELATED ROUTINES: 
VBLKOF - unblanks the video display 
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BOS CALLS 


ROUTINE NAME: VCOLRT 


FUNCTION: 


Set the colour table address in the TMS9918A. 


DESCRIPTION: 


This routine is used to set the colour table address in the 
TMS9918A. The full colour table address is passed in reg 
BC. This routine correctly writes the address into the 9918 
reg 3 and stores the full colour table address in VCOLRAD 
for use by other routines. This routine works in Graphics 
II Mode by setting all the most significant bits as 
required by the VDP 


PARAMETERS PASSED: 


BC Reg: Base Address of COLOUR Table 


PARAMETERS RETURNED: 


NONE 


REGISTERS USED: 


A, BC, E, HL, Flags 
4 Bytes of Stack 


ROUTINE TYPE GLOBAL - BOS No. 7 - Re-entrant 


COMMENTS AND WARNINGS: 


Spec. 


The colour table must be set up for programs using 
GRAPHICS 1 or GRAPHICS 2. 
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BOS CALLS 


ROUTINE NAME: VFILL 


FUNCTION: 
Fill a block of Video RAM with one character 


DESCRIPTION: 
This routine will fill any contiguous portion of VRAM with 
a particular value. The value to fill with is passed in 
the E register, the length to fill is passed in the BC 
pair. The Address in VRAM is passed in HL 


PARAMETERS PASSED: 
BC = length to fill 
E = value to fill with 
HL = address in VRAM to start 


PARAMETERS PASSED: 
None 


PARAMETERS RETURNED: 
None 


REGISTERS USED: 
A,B,C,D,E,F,H,L 
4+ Bytes of stack used 


ROUTINE TYPE GLOBAL - BOS No. 1E - Re-entrant 


COMMENTS AND WARNINGS: 
This allows the application program, which resides in RAM, 
to keep from having to define large tables in RAM 
containing the same entry over and over again, and then 
copying the table into Video RAM. 
This routine can be used to pad out pattern tables with 
the number for blanks or fill colour tables with one 
combination of colours. 
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BOS CALLS 


ROUTINE NAME: VMOVD 


FUNCTION: 
Quickly move data from one location in VRAM to another. 


DESCRIPTION: 
This routine will quickly move data from one location in 
VRAM to another. The data area must be less than 255 bytes 
long. The move is made by starting at the locations 
specified and moving DOWN in VRAM 


PARAMETERS PASSED: 
C Reg: Amount of data to be moved in bytes 
DE Reg: End Address where data is located 
HL Reg: End Address where data is to be moved to 


PARAMETERS RETURNED: 
DE Reg: One before the beginning of the source data area 
HL Reg: One before the beginning of the destination data area 


REGISTERS USED: 
A, BC, DE, HL, Flags 
4 bytes of stack used 


ROUTINE TYPE GLOBAL ~ BOS No. 3B - Re-entrant 


COMMENTS AND WARNINGS: 

Calling this routine with C reg equal to zero will cause 
256 bytes of data to be transferred. This routine disables 
interrupts for the full data transfer. This may cause 
interrupts to be lost. 

NOTE: If the value in HL is greater than the value in 
DE minus the value of C, then the difference will be the 
number of bytes "clobbered" at the start of the block of 
data being moved. 


RELATED ROUTINES: 
VMOVI - move data in Video RAM (incrementing from 
given address) 
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BOS CALLS 


ROUTINE NAME: VMOVI 


FUNCTION: 
Quickly move data from one location in VRAM to another. 


DESCRIPTION: 
This routine will quickly move data from one location in 
VRAM to another. The data area must be less than 255 bytes 
long. The move is made by starting at the locations 
specified and moving UP in VRAM 


PARAMETERS PASSED: 
C Reg: Amount of data to be moved in bytes 
DE Reg: Start Address where data is located 
HL Reg: Start Address where data is to be moved to 


PARAMETERS RETURNED: 
DE Reg: One past the end of the source data area 
HL Reg: One past the end of the destination data area 


REGISTERS USED: 
A, BC, DE, HL, Flags 
4 bytes of stack used 


ROUTINE TYPE GLOBAL ~ BOS No. 3A - Re-entrant 


COMMENTS AND WARNINGS: 
Calling this routine with C reg equal to zero will cause 
256 bytes of data to be transferred. This routine disables 
interrupts for the full data transfer. This may cause 
interrupts to be lost. 

NOTE: If the value in HL is less than the value in DE 
plus the value of C, then the difference will be the 
number of bytes "clobbered" at the end of the block of 
data being moved. 


RELATED ROUTINES: 
VMOVD - move data in VRAM (decrementing from given 
address) 
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BOS CALLS 


ROUTINE NAME: VNAMET 


FUNCTION: 
Set the pattern name address of the TMS9918A. 


DESCRIPTION: 
This routine is used to set the pattern name address of the 
TMS9918A. The full pattern name address is passed in reg 
BC. This routine correctly writes the address into the 
9918 reg 2 and stores the full pattern name address in 
VNAMEAD for use by other routines. 


PARAMETERS PASSED: 
BC Reg: 16 bit base address of NAME Table 


PARAMETERS RETURNED: 
NONE 


REGISTERS USED: 
A, BC, E, HL, Flags 
4 Bytes of Stack Used 


ROUTINE TYPE GLOBAL ~ BOS No. 6 - Re~entrant 


COMMENTS AND WARNINGS: 
The mode that the application is working in should 
already be set, i.e. TEXT or GRAPHICS 1 or GRAPHICS 2. 
The address should be set in accordance to the mode chosen. 


RELATED ROUTINES: 
VCOLRT - set colour table base address 


VPTRNT - set pattern table base address 
VSATRT - set sprite attribute table base address 
VSPRST - set sprite pattern table base address 
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BOS CALLS 


ROUTINE NAME: VPTRNT 


FUNCTION: 
Set the pattern table address in the TMS9918A. 


DESCRIPTION: 

This routine is used to set the pattern table address in 
the TMS9918A. The full pattern table address is passed in 
reg BC. This routine correctly writes the address into the 
9918 reg 4 and stores the full pattern table address in 
VPTRNAD for use by other routines. This routine works 
correctly in GRAPHICS Mode II by setting all the most 
significant bits to l. 


PARAMETERS PASSED: 
BC Reg: Base Address of PATTERN Table 


PARAMETERS RETURNED: 
NONE 


REGISTERS USED: 
A, BC, E, HL, Flags 
4 Bytes of Stack 


ROUTINE TYPE GLOBAL - BOS No. 8 - Re~entrant 

COMMENTS AND WARNINGS: 
The mode that the application is working in should 
already be set, i.e. TEXT or GRAPHICS 1 or GRAPHICS 2. 
The address should be set in accordance to the mode chosen. 


RELATED ROUTINES: 


VCOLRT - set colour table base address 

VNAMET - set name table base address 

VSATRT - set sprite attribute table base address 
VSPRST - set sprite pattern table base address 
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BOS CALLS 


ROUTINE NAME: VRAMD8 


FUNCTION: 
Dump a string of bytes from the VRAM. 


DESCRIPTION: 

This routine is functionally the same as FASTD8 but are 
safe in an interrupt environment (and also take longer). 
This routine is used to dump a string of bytes from the 
VRAM. The length of the data to be dumped is passed in 
reg C and the memory address, in RAM, of the destination 
of the data is passed in reg DE. The start address in 
VRAM is passed in HL. This routine can be used on strings 
up to 256 bytes in length. 


PARAMETERS PASSED: 
C Reg: Length of data block to be dumped 
DE Reg: Start of destination area in RAM 
HL Reg: Start of source area in VRAM 


PARAMETERS RETURNED: 
HL Reg: Points one byte past end of source area 
in VRAM 
(Useful for "Chaining" Calls) 


REGISTERS USED: 
A, BC, DE, HL, Flags 
6 Bytes of Stack Used 


ROUTINE TYPE GLOBAL ~- BOS No. 15 - Re-entrant 


COMMENTS AND WARNINGS: 
This routine is safe for use in an interrupt environment. 
If more than 256 bytes are to be moved use the routine 
VRAMDU. 


RELATED ROUTINES: 
VRAMDU - Video RAM dump 
FASTD8 -~ Fast Video RAM dump (less than 256 bytes) 
FASTDU - Fast Video RAM dump 
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BOS CALLS 


ROUTINE NAME: VRAMDU 


FUNCTION: 
Dump a string of bytes from the VRAM. 


DESCRIPTION: : 
This routine is functionally the same as FASTDU, but are 
safe in an interrupt environment (and also take longer). 
This routine is used to dump a string of bytes from the 
VRAM. The length of the data to be dumped is passed in 
reg BC and the memory address of the destination of the 
data is passed in reg DE. The start address in VRAM is 
passed in HL. Since 16 bit pointers are used, anywhere 
from 0 to 16K of data may be transfered with this routine. 


PARAMETERS PASSED: 
BC Reg: Length of data block to be dumped 
DE Reg: Start of destination area in RAM 
HL Reg: Start of source area in VRAM 


PARAMETERS RETURNED: 
HL Reg: Points one byte past end of source area in VRAM. 
(Useful for "Chaining" Calls) 


REGISTERS USED: 
A, BC, DE, HL, Flags 
6 Bytes of Stack Used 


ROUTINE TYPE GLOBAL - BOS No. 16 - Re-entrant 

COMMENTS AND WARNINGS: 
This routine is safe for use in an interrupt environment. 
If a small string (less than 256 bytes) is to be dumped, 
use the routine VRAMD8 


RELATED ROUTINES: 


VRAMD8 - Video RAM dump (less than 256 bytes) 
FASTD8 - Fast Video RAM dump (less than 256 bytes) 
FASTDU - Fast Video RAM dump 
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BOS CALLS 


ROUTINE NAME: VRAML8 


FUNCTION: 
Write a string of bytes to the VRAM. 


DESCRIPTION: 
This routine is functionally the same as FASTL8 but are 
safe in an interrupt environment (and also take longer). 
This routine is used to write a string of bytes to the 
VRAM. The length of the data to be written is passed in 
reg C and the memory address of the source of the data is 
DE. The start address in VRAM is passed in reg HL. 


PARAMETERS PASSED: 
C Reg: Length of data block to be read 
DE Reg: Start of source area in RAM 
HL Reg: Start of destination area in VRAM 


PARAMETERS RETURNED: 
HL Reg: Points one byte past end of destination area 
in VRAM 
(Useful for "Chaining" Calls) 


REGISTERS USED: 
A, BC, DE, HL, Flags 
6 Bytes of Stack Used 


ROUTINE TYPE GLOBAL - BOS No. 13 - Re-entrant 


COMMENTS AND WARNINGS: 
This routine is safe for use in an interrupt environment. 
If more than 256 bytes of data must be loaded into Video 
RAM, use the routine VRAMLD. 


RELATED ROUTINES: 
VRAMLD - load Video RAM 
FASTL8 - quick load of Video RAM (less than 256 bytes) 
FASTLD - quick load of Video RAM 
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BOS CALLS 


ROUTINE NAME: VRAMLD 


FUNCTION: 
Write a string of bytes to the VRAM. 


DESCRIPTION: 

This routine is functionally the same as FASTLD, but are 
safe in an interrupt environment (and also take longer). 
This routine is used to write a string of bytes to the 
VRAM. The length of the data to be written is passed in 
reg BC and the memory address of the source of the data is 
passed in reg DE. The start address in VRAM is passed in 
HL. Since 16 bit pointers are used, anywhere from 0 to 16K 
of data may be transfered with this routine. 


PARAMETERS PASSED: 
BC Reg: Length of data block to be read 
DE Reg: Start of source area in RAM 
HL Reg: Start of destination area in VRAM 


PARAMETERS RETURNED: 
HL Reg: Points one byte past end of destination area 
in VRAM 
(Useful for "Chaining" Calls) 


REGISTERS USED: 
A, BC, DE, HL, Flags 
6 Bytes of Stack Used 


ROUTINE TYPE GLOBAL - BOS No. 14 - Re-entrant 
COMMENTS AND WARNINGS: 
This routine is safe for use in an interrupt environment. 


If a small string (less than 256 bytes) is to be loaded 
use VRAML8. 


RELATED ROUTINES: 


VRAMD8 - Video RAM dump (less than 256 bytes) 
FASTD8 ~ Fast Video RAM dump (less than 256 bytes) 
FASTDU - Fast Video RAM dump 
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BOS CALLS 


ROUTINE NAME: VRAMRD 


FUNCTION: 
Read a single byte of data from TMS9918A VRAM 


DESCRIPTION: 
This routine is used to read a single byte of data from 
TMS9918A VRAM. The address to be read is passed in reg BC, 
the value of the VRAM at that location is returned in reg 
A. 


PARAMETERS PASSED: 
BC Reg: Location of VRAM to be read from 


PARAMETERS RETURNED: 
A Reg: Contents of VRAM at Location 


REGISTERS USED: 
A,F 
4 bytes of stack used 
ROUTINE TYPE GLOBAL ~ BOS No. OD ~- Re~entrant 


COMMENTS AND WARNINGS: 


None 
RELATED ROUTINES: 
VRAMWR - write one byte to Video RAM 
FASTRD - quick read of one byte to Video RAM 
FAS TWR - quick write of one byte to Video RAM 
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BOS CALLS 


ROUTINE NAME: VRAMWR 


FUNCTION: 
Write a single byte of data to TMS9918A VRAM 


DESCRIPTION: 
This routine is used to write a single byte of data 
TMS9918A VRAM The address to be written is passed in 
BC. The data to be written is passed in Register E. 


PARAMETERS PASSED: 
BC Reg: Location of VRAM to be written to 
E Reg: Data to be written 


PARAMETERS RETURNED: 
NONE 


REGISTERS USED: 
A, BC, flags 
4 bytes of stack used 
ROUTINE TYPE GLOBAL - BOS No. OE ~ Re-entrant 


COMMENTS AND WARNINGS: 
None 


RELATED ROUTINES: 


VRAMRD - read one byte of Video RAM 
FAS TRD - read one byte of Video RAM ... fast 
FAS TWR ~ write one byte of Video RAM ... fast 


from 
reg 
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BOS CALLS 


ROUTINE NAME: VREGRD 


FUNCTION: 
Reads the TMS9918A video display register 


DESCRIPTION: 
This routine reads the TMS9918A video display register 
values, which are stored in RAM images. The register 
number to be written (0 to 7) is passed in reg C. 


The following data may also be read: 

8: VDP Status Register RAM Image (Updated Each Clock Interrupt 
9: Current VDP Mode: 0 ~text, 1 -Graphics I, 2 -Graphics II 

A: Current Screen Width in Characters 


The data is returned in register A 


PARAMETERS PASSED: 
C Reg: Register Number to be read 


PARAMETERS RETURNED: 
A Reg: Value of Register 


REGISTERS USED: 
A, BC, HL, Flags 
0 Bytes of stack used 


ROUTINE TYPE GLOBAL ~ BOS No. 0 - Re-entrant 


COMMENTS AND WARNINGS: 

The actual control registers of the video chip are 
write only. The IOS maintains an image of these registers 
allowing the application to "read" the values that are 
currently in the registers. 


RELATED ROUTINES: 
VREGWR - write to a register in the video chip 
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BOS CALLS 


ROUTINE NAME: VREGWR 


FUNCTION: 
Writes the TMS9918A video display registers. 


DESCRIPTION: 
This routine writes the TMS9918A video display registers. 
The register number to be written (0 to 7) is passed in reg 
C and the data to be written is passed in reg E. Note that 
Since the TMS9918A registers are write-only, images of the 


registers are kept in global memory where they may be read 
if required. 


PARAMETERS PASSED: 
C Reg: Register Number to be written 
E Reg: Data to be written into register 


PARAMETERS RETURNED: 
NONE 


REGISTERS USED: 
A, BC, E, HL, Flags 
4 Bytes of Stack Used 
ROUTINE TYPE GLOBAL - BOS No. 4 - Re-entrant 


COMMENTS AND WARNINGS: 
None 


RELATED ROUTINES: 
VREGRD ~ read a register in the Video chip 
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BOS CALLS 


ROUTINE NAME: VSATRT 


FUNCTION: 


Set the sprite attributes table address in the TMS9918A. 


DESCRIPTION: 


This routine is used to set the sprite attributes 
address in the TMS9918A. The full sprite attributes 


routines. 


PARAMETERS PASSED: 
BC Reg: Base Address of Sprite ATTRIBUTES table 


PARAMETERS RETURNED: 
NONE 


REGISTERS USED: 
A, BC, E, HL, Flags 
4 Bytes of Stack 


ROUTINE TYPE GLOBAL ~- BOS No. 9 = Re-entrant 
COMMENTS AND WARNINGS: 


This routine must be called when setting up the video 
GRAPHICS 1 or GRAPHICS 2 mode. 


table 
table 
address is passed in reg BC. This routine correctly writes 
the address into the TMS9918A reg 5 and stores the 
sprite attributes table address in VATRIAD for use by other 


full 


for 
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BOS CALLS 


ROUTINE NAME: VSETG1 


FUNCTION: 
Set video for graphics 1 mode 


DESCRIPTION: 
VSETG1 sets the VDP for graphics 1 mode, blanked display, 
16*16 sprites, 1X magnification. The user must use the 
VBLKOFF routine to enable the display. 


PARAMETERS PASSED: 
None 


PARAMETERS RETURNED: 
None 


REGISTERS USED: 
A,B,C,D,E,F 
2 Bytes of stack used 


ROUTINE TYPE GLOBAL ~ BOS No. 26 - Re-entrant 


COMMENTS AND WARNINGS: 
This routine does not set base addresses of tables nor 
does it load pattern sets into Video RAM. 


RELATED ROUTINES: 
VSETG2 - set to GRAPHICS 2 mode 
VSETTX - set to TEXT mode 
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ROUTINE NAME: VSETG2 


FUNCTION: 
Set video for graphics 2 mode 


DESCRIPTION: 


VSETG2 sets the VDP for graphics 2 mode, blanked display, 
16*16 sprites, 1X magnification. The user must use the 


VBLKOFF routine to enable the display. 


PARAMETERS PASSED: 
None 


PARAMETERS RETURNED: 
None 


REGISTERS USED: 
A,B,C,D,E,F 
2 Bytes of stack used 


ROUTINE TYPE GLOBAL - BOS No. 27 ~ Re-entrant 


COMMENTS AND WARNINGS: 
This routine does not set base addresses of 
does it load pattern sets into Video RAM. 


RELATED ROUTINES: 
VSETG1 - set to GRAPHICS 1 mode 
VSETTX - set to TEXT mode 


tables 


nor 
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ROUTINE NAME: VSETSP 


FUNCTION: 


Set sprite size and magnification 


DESCRIPTION: 


VSETSPA sets the sprite size and magnification. The sprite 
size is passed in the C register (0=8*8, 1=16*16). The 
sprite magnification is passed in the E register (0=1X, 
1=2X). The user must first set the mode using one of the 
above three routines. 


PARAMETERS PASSED: 
Cc 


= sprite size (0 = 8*8,1 = 16*16) 


E sprite magnification (0 =lx,l =2x) 


PARAMETERS RETURNED: 


None 


REGISTERS USED: 


A,B,C,D,E,F,H,L 
2+ Bytes of stack used 


ROUTINE TYPE GLOBAL - BOS No. 28 - Re-entrant 


COMMENTS AND WARNINGS: 


Spec. 


Defaults for sprite size and magnification are set when 
the mode (TEXT, GRAPHICS 1, or GRAPHICS 2) is set 
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ROUTINE NAME: VSETTX @ 


FUNCTION: 
Set video for text mode 


DESCRIPTION: 
VSETTXT sets the VDP for text mode, blanked display, 16*16 
Sprites, 1X magnification. Please NOTE that sprites will 
NOT appear in text mode even though the video chips' 
registers are set up for sprites. The user must use the 
VBLKOFF routine to enable the display. 


PARAMETERS PASSED: 
None 


PARAMETERS RETURNED: 
None 


REGISTERS USED: 
A,B,C,D,E,F 
2 Bytes of stack used 


ROUTINE TYPE GLOBAL - BOS No. 25 - Re-entrant 


COMMENTS AND WARNINGS: r 
Sprites can not be used in text mode, however when setting 
the VDP register, sprite information must be provided. 
This routine does not set base addresses of tables nor 
does it load pattern sets into Video RAM. 


RELATED ROUTINES: 
VSETG1 - set to GRAPHICS 1 mode 
VSETG2 - set to GRAPHICS 2 mode 
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ROUTINE NAME: VSPRST 


FUNCTION: 
Set the sprite table address in the TMS9918A. 


DESCRIPTION: 
This routine is used to set the sprite table address in the 
TMS9918A. The full sprite table address is passed in reg 
BC. This routine correctly writes the adddress into the 
TMS9918A reg 6 and stores the full sprite table address 
into VSPRIAD for use by other routines. 


PARAMETERS PASSED: 
BC Reg: Base Address of Sprite PATTERN table 


PARAMETERS RETURNED: 
NONE 


REGISTERS USED: 
A, BC, E, HL, Flags 
4 Bytes of Stack 
ROUTINE TYPE GLOBAL - BOS No. OA - Re-entrant 
COMMENTS AND WARNINGS: 
The mode in which the video chip is to work should 
already be set. 


RELATED ROUTINES: 


VNAMET - set the name table base address 

VCOLRT ~- set the colour table base address 

VPTRNT - set the pattern table base address 

VSATRT - set the sprite attribute table base address 

VSPRST - set the sprite definition table base 
address 
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ROUTINE NAME: VSTATR 


FUNCTION: 
Reads the status register of the TMS9918A 


DESCRIPTION: 
This routine reads the status register of the TMS9918A and 
returns the register contents in reg A. The status register 
image VSTATUS is also updated. This routine may cause 
clock interrupts to be lost as it executes, since it will 
reset any pending interrupt. 


PARAMETERS PASSED: 
NONE 


PARAMETERS RETURNED: 
A Reg: VDP Status Byte 


REGISTERS USED: 
A,B,HL,C,F 
2+ Bytes of stack used 


ROUTINE TYPE GLOBAL ~- BOS No. 5 ~ Re-entrant 


COMMENTS AND WARNINGS: 
This is a dangerous call! It may cause Clock Interrupts to 
be lost. Unless absolutly necessary, it is best to get the 
VDP Status by reading VSTATUS using VREGRD. VSTATUS will 
be updated every 16 msec. by the clock ISR. 
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r ROUTINE NAME: VTABRD 


FUNCTION: 
Reads the current table base address pointers 


DESCRIPTION: 
This routine reads the current table base address pointers 
in the VDP from a RAM image area. The number of the 
pointer to be read is passed in register C. These numbers 
are as follows: 


0: VNAMEAD -Name Table Base Address 

1: VCOLRAD -Colour Table Base Address 

2: VPTRNAD ~Pattern Table Base Address 

3: VATRIAD ~-Sprite Attribute Table Base Address 
4: VSPRIAD ~Sprite Pattern Table Base Address 


PARAMETERS PASSED: 
C Reg: Register Number to be read 


PARAMETERS RETURNED: 
HL Reg: Register value 


REGISTERS USED: 
@ A, BC, DE, HL, Flags 
0 Bytes of stack used 
ROUTINE TYPE GLOBAL - BOS No. 1 - Re-entrant 


COMMENTS AND WARNINGS: 
None 


RELATED ROUTINES: 
VNAMET - set the name table base address 


VCOLRT - set the colour table base address 

VPTRNT ~ set the pattern table base address 

VSATRT - set the sprite attribute table base address 

VSPRST ~ set the sprite definition table base 
address 
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ROUTINE NAME: XYLOC 


FUNCTION: 
Return name table address for any X-Y location on screen 


DESCRIPTION: 
XYLOC returns the name table address in VRAM for any X-¥ 
location on the screen. The X location is passed in the C 
register, the Y location in the E register. The VRAI 
address is returned in both HL and BC. 


PARAMETERS PASSED: 
C = X location (column) on screen 
E = ¥ location (row) 


PARAMETERS RETURNED: 
BC = address in VRAM 
HL = address in VRAM 


REGISTERS USED: 
BC, DE,HL 
Stack use = 4 bytes 


ROUTINE TYPE GLOBAL - BOS No. 1F - Re-entrant 


COMMENTS AND WARNINGS: 
NOTE: The screen is 32x24 patterns in the GRAPHICS modes 
and 40x24 patterns in TEXT mode. If a standard T.V. set 
is being used, the first and last column of patterns may 
fall just outside the screen. 
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EXTENDED IOS 


Introduction 


The I0S is divided into 2. sections. The Kernel 
contains the minimum set of IOS functions, while the 
Extended IOS (XIOS) contains the varied extensions. 
This structuring of the IOS is done to leave as much 
programming space as possible for applications, while 
not reducing or limiting the functionality of the IOS. 
As new features, such as I/O drivers for the varied 
option boards, are added to the IOS, they will be 
placed into the XIOS section thereby keeping the Kernel 
size to a minimum. 


The XIOS system is located in 16 different segments on 
the wheel. These segments represent 16 tiering levels 
for billing purposes - ie. the uSer of the application 
must be authorized for the particular segment required 
by the application program. Each segment is divided 
into a number of modules ( 0 through 15 ). Each module 
contains a related set of functions. XIOS modules are 
loaded by the application by specifying which segment 
the module is found in (0 -> 15) and then within that 
segment which XIOS module is desired (again a number 
between 0 and 15). As they are loaded, these modules 
will be relocated immediately below the IOS Kernel. 
When an application no longer needs a module, it may 
delete or unload that module. The Kernel software is 
responsible for tracking which modules are currently 
operative and which ones are not. 


Locations 6 and 7 will always point to the base of the 
total I0S, Kernel plus Extended. This will enable 
applications to know how much space is available. 
Applications normally place the stack based on the 
value of locations 6 and 7. 


Care must be taken that the stack is not overwritten 
when loading XIOS modules. Ensure that your stack is 
not at the top of user memory when requesting an XIOS 
module - that is where the XIOS module will load to. 


Extended IOS Module Handler 
The XIOS module handier is responsible for loading, 


unloading, linking and keeping track of XIOS modules. 
This handler is included in the IOS Kernel. 
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© 5.2.1 Memory Structure for Loaded XIOS Modules 


The structure for memory allocation of XIOS modules is 
depicted in the following diagram: 


; 1 
| IOS | 
| KERNEL ! 
{ | 
| i] 


BOTTOM OF KERNEL 


XIOS MODULE 2 


BOTTOM OF LOWEST XIOS 


0008 | JUMP TO BOTTOM OF KERNEL 
0005 | JUMP TO BOTTOM OF LOWEST XIOS 
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§.2.2 Loading XIOS Modules 


XIOS modules will be loaded in one module at a time. 
The module will be loaded in and relocated next to the 
very bottom of the current IOS. Locations 6 and 7 will 
be amended to reflect a bottom for I0S. Should 
difficulties occur in loading and initializing the XxIOS 
module, the returned error code will indicate why 
failure occurred. 


The command to load an XIOS module is a DOS command with the 
following format: 


LOAD_XIOS_MODULE (call number 96H) 
Function: Load one XIOS module 
Entry Parameters: Register C = 96H 


Register E = XIOS Module ID 
Where XIOS Module ID is one of: 
00 ~ Basic BDOS and BIOS 
01 - Basic BDOS, Extended BDOS and BIOS 
13 ~ Multi-Window Screen Driver 
14 ~ 80 Column Screen Driver 


Exit Parameters: Register A = Status 
where Status is one of: 
00 ~- Load was successful 
Segment handler error codes: 
~1 - XIOS Module was not loaded because 
tier is not authorized 
-2 ~ XIOS Module was not loaded because 
segment buffer overflowed 
-3 ~ XIOS Module was not loaded because 
adaptor did not respond 
-4 - XIOS Module was not loaded because 
an incorrectly formated packet 
was received 
-5 - XIOS Module was not loaded because 
an undetermined communications 
protocol error occurred 
-6 - XIOS module was not loaded because 
it was not located in the segment 
XIOS Module error codes: 
Codes ~10H to -70H are reserved for XIOS 
Module to return after initializing. 
These codes will be described in detail 
in each respective XIOS Section. 
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@ Each module is described in detail as to function and the type of 
support it needs with regard to hardware and other XIOS modules, 
in later sections of the APG. 
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5.2.3 Unloading XIOS Modules 


XIOS modules will be unloaded or deleted one module at a 
time. Only the module at the very bottom of the IOS can 
be unloaded. When this happens, locations 6 & 7 will be 
amended to reflect the new bottom for the I0S, and 
indicate that memory has been freed up. In order to 
unload all XIOS modules, the application must unload 
them one at a time, until the return code indicates that 
no module was unloaded. 


Note that when the application is terminated normally by 
a jump to location 0 or via the EXIT key on the keyboard 
(an IOS function), all resident xXIOS modules are 
unloaded by the IOS re-boot code. This ensures that any 
hardware that may be "attached" to an XIOS module (eg. 
disk drives) is properly de-initialized (eg. drive motor 
is turned off). 


The command to unload an XIOS module is a DOS command with the 
following format: 


UNLOAD_XIOS_MODULE (call number 97H) 
Function: Unload one XIOS module 
Entry Parameters: Register C = 97H 


Exit Parameters: Register A = Status 
where Status is one of: 
00 - Unload was successful and 
unloaded module number is found 
in register L 
-1 - There was no XIOS module to unload 
XIOS Module error codes: 
Codes -10H to -70H are reserved for 
XIOS Module to return after 
de-~initializing. These codes will be 
described in detail in each respective 
XIOS Section. 


Register L = XIOS Module ID 
where XIOS Module ID is one of: 
00 - Basic BDOS and BIOS 
01 - Basic BDOS, Extended BDOS and BIOS 
13 - Multi-Window Screen Driver 
14 - 80 Column Screen Driver 


Each module is described in detail as to function and the type of 
support it needs with regard to hardware and other XIOS modules, 
in later sections of the APG. 
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5.2.4 Resolving References in XIOS Modules 


Different XIOS modules will require access to data 
structures and subroutines contained within other xXIOS 
modules or within the Kernel. 


DOS call number 99H provides ‘the mechanism for resolving 
references. This call returns the address of the global 
variable requested. All XIOS modules containing global 
variables or subroutines must trap and execute this DOS 
call. Each global variable must be given a unique 
reference number. These reference numbers will be 
included in the respective section for the XIOS module, 
further on in this specification. 


The call has the following format: 


RESOLVE_REFERENCE (call number 99H) 


Function: 


To return the address of the requested global reference 


Entry Parameters: Register C = 99H 


Register E = XIOS Module ID 
where XIOS Module ID is one of: 
G0 - Basic BDOS and BIOS 
01 - Basic BDOS, Extended BDOS, and BIOS 
13 - Multi-Window Screen Driver 
14 - 80 Column Screen Driver 
FF - IOS Kernel 


Register D = Reference Number as defined for 
each respective XIOS Module. This num- 
ber has the range from 00 to FFH. 


Exit Parameters: Register A = Status 
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where Status is one of: 


00 - Search was successful with the 
address being returned in Register 
HL 


-1 - XIOS Module was not found and no 
address is being returned 

-2 - Reference number was not found and 
no address is being returned 


Register HL = Address of the global reference 


XIOS ~ DISK HANDLING 


5.3 DISK SYSTEM 
§.3.1 Introduction 


The floppy disk units are attached to the Nabu PC via an 
interface card. The interface card is capable of supporting up to 
two disk drives. Each drive can be single or double density, 
single or double sided, full height or half height, 48 or 96 tpi. 
The disk drive currently provided is a single sided double dens- 
ity half height unit with 48 tpi. 


New diskettes must be formatted to a recognizable format. 
The Nabu standard format is 40 tracks per side, soft sectored 
with 5 sectors per track and 1024 bytes per sector. The software 
is able to read single or double density disks produced by CP/M 
systems on Xerox 820, Cromemco, Osborne, {Kaypro} or IBM PC's. 


PROGRAM RESPONSIBILTY 


Storage of retrieval of data files are the responsibility of 
the individual application programs. Creation or modification of 
files must be handled, as well as intercepting and interpreting 
error codes from the file subsystem. 


The only independant responsibility the end user has is in 
disk maintenance, i.e. format, backup, copy etc etc.. This res- 
ponsibility is handled by the disk utility application programs 
as described in the disk utility manuals. 


FILES AND DIRECTORY 


The files stored on disk are CP/M version 3.0 files, stored 
in a CP/M directory and all calls to the directory and file 
handling routines are standard CP/M. The routines to do file 
Management are supplied by Digital Research Inc. and are normally 
referred to as the BDOS. The BDOS interfaces to low level disk 
access routines called the BIOS. Application routines should do 
all disk access via the proper BDOS calls. 


The Console Command Processor usually a part of the CP/M 
operating system, does not exist in the cable environment and the 
equivalent functions are handled via other routines. 


DISK ERROR HANDLING 


Errors detected by the BIOS or BDOS will be returned to the 
calling program, rather than resulting in an error on the users 
console. Application programs need to test the appropriate status 
on return from a BDOS call. 
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WARNING 


The disk routines use the same buffer area in IOS as_ the 
segment handler. Therefore, before accessing the segment 
handling routines in IOS while you have open disk files, it is 
strongly recommended that you close all files, perform the 
segment load(s) then reset the disk system. 


Programmers should reference the CP/M documentation directly 
about the CP/M disk features and programming requirements. In 
particular, the CP/M Plus User's guide - gives an overview of the 
organization and access of CP/M files. The CP/M plus programmer's 
guide gives detailed descriptions, especially sections: 


2.1 Calling Conventions 
2.3  BDOS File System 
3. BDOS calls (refer only to file access calls) 


Programmers should be aware that the disk files are handled by 
the DRI supplied routines, and that any other CP/M features have 
been implemented by Nabu in a compatible form. Section 4.2 of 
this guide deals with CP/M compatible calls, and contains a list 
of all calls. 


CP/M Version 3.0 


Version 3.0 of CP/M has several enhancements that will be of 
value to programmers. The extensions included in the disk support 
are the following: 


Time and date stamping on files - refer to section 2.7.2 of 
the CP/M user's guide and section 2.3.8 of the CP/M 
programmer's guide. 


Automatic diskette login - refer to section 2.3.11 of the 
CP/M programmer's guide. 


End of file marking ~- refer to section 2.3.12 of the 
CP/M programmer's guide. 


Error trapping and return to program - see section 2.3.13 of 
the CP/M programmer's guide. 


Maximum file size is now 32Mb per file. 


The application programmer needs to set up only a_e single 
control block (File Control Block - FCB) to access a file. Refer 
to section 2.3.3 of the CP/M programmer's guide. 
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5.4 MULTI-WINDOW SCREEN DRIVER 


5.4.1 INTRODUCTION 


This XIOS module will contain a complete set of routines 
which form the multi-window screen driver. These 
routines were formerly BOS routines contained within the 
IOS Kernel. 


5.4.2 OPERATIONAL REQUIREMENTS 


This XIOS module will not require any other XIOS module 
in order for it to function. It does however use BOS 
calls from within the IOS Kernel to interface with the 
video hardware. 


5.4.3 MODULE SPECIFIC ERROR CODES 


This xXIOS module will not return any error codes 
specific to itself, when it has been loaded, and when 
the module has finished initialization or de- 
initialization. 


5.4.4 MODULE INITIALIZATION 
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When this XIOS module is loaded, its initialization 
procedure is executed. This procedure will do the 
following: 


1. Link into the IOS Kernel BOS routines as 
required. 

2. Disable the previous screen driver. 

3. Set the video screen to text mode. 

4. Fill the video screen with a blue background 
and a blue foreground. 

5. Create window #1 with size 38 columns by 24 
rows; the cursor will be a flashing underline 
character. 

6. Enable the video hardware to output to screen. 

7. Enable the cursor to flash. 


Windows 2, 3, 4, and 5 will be undefined after 
initialization. 
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5.4.4 MODULE DE-INITIALIZATION 


Prior to the module being physically removed from 
memory, a "shut-down" or de-initialization procedure is 
executed. This procedure will do the following: 


1. Clear the screen by filling with blanks. 

2. Restore the Kernel routines such as the clock 
interrupt handler, to their "prior to xXIOS 
module" state. 


This procedure can not and will not restore the total 
context of the screen prior to the XIOS module being 
loaded. 


5.4.5 DOS CALL INTERFACE 


This module will be capable of decoding and executing 
four DOS calls. The call numbers decoded are: 


8F -- DEFINE WINDOW 

99 -~ RETURN GLOBAL ADDRESS OF BOS ROUTINE 
A2 -- INPUT STATUS FROM VIDEO SCREEN WINDOW 
A3 -- OUTPUT DATA TO VIDEO SCREEN WINDOW 


DEFINING VIDEO SCREEN WINDOWS 


Up to five windows may be defined. Upon initialization 
window 1 is set up to be the full text screen. Windows 
may be altered or removed with the following call: 


DEFINE_WINDOW (call number 8FH) 


Function: Used to define a screen window for use by 
the VIDEO_SCREEN calls below 


Entry Parameters: Register C = 8F Hex 
Register DE = Pointer to 
WINDOW_DEFINITION_BLOCK 


Exit Parameters: Register HL = Pointer to old 
WINDOW_CONTROL_BLOCK 
or 
zero if no old WCB 
exists 


Cautions: This routine is not re-entrant. 
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The window is defined via the following two data 
structures: 


WINDOW_DEFINITION_BLOCK: 


DEVICE_LOCATION: BYTE; 
WCB_POINTER: ADDRESS; 


Where: 


DEVICE_LOCATION contains the single byte 
number of the window being defined. It has a 
range of 1 to 5. 

WCB_POINTER contains a two byte pointer to a 
valid window control block. If this value is 
zero, the window becomes undefined, and thus 
the window is closed. 


WINDOW_CONTROL_BLOCK: 


TOP_LEFT_ADDRESS: WORD; 


COLUMN_WIDTH: BYTE; 
ROW_DEPTH : BYTE; 
CURSOR_TYPE: BYTE; 
CURSOR_PATTERN: BYTE; 
CURSOR_X_POS: BYTE; 
CURSOR_Y_POS: BYTE; 
TAB_MAP: ARRAY[1..39] OF 


BOOLEAN ; 


Where: 


TOP_LEFT_ADDRESS contains a two byte value. 
This value is computed as follows: 
TOP_LEFT_ADDRESS = row number * 40 
+ column number 
Where: the row number and column 
number represent the top 
left corner of the window 
This value has arange of 0 to 959 
decimal 
COLUMN_WIDTH contains a one byte value. It 
is the number of columns the window is 
wide. It has a range of 1 to 40. 
ROW_DEPTH contains a one byte value. It is 
the number of rows the window is deep. 
It has a range of 1 to 24. 


Spec. 
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CURSOR_TYPE contains a one byte value. Two 
bits are defined as follows: 


bit 0 set indicates a visible 


exists 


cursor 


bit 0 clear indicates no visible cursor 


exists 


bit 7 set indicates the cursor 


flash 


‘is to 


bit 7 clear indicates the cursor is to 


be steady 


PATTERN_NAME contains a one byte value. It 
is the ASCII character which is to be 
the cursor shape. The default window 


uses the underline character. 


CURSOR_X_POS contains a one byte value. It 


is the relative cursor column 


position 


within the window. It has a range of 0 
to COLUMN_WIDTH-1. It is usually set to 


0. 


CURSOR_Y_POS contains a one byte value. It 
is the relative cursor row position 
within the window. It has a range of 0 
to ROW_DEPTH-1. It is usually set to 0. 


TAB_MAP contains an array of 40 


bits (5 


bytes). These bits identify tab stops. 
If a bit is set, then a tab stop exists 
at that relative column number in the 


window. 


DEFINE_LWINDOW initializes one of the five windows (1 


to 5) which are associated with the Video 
Physical Devices 1 to 5. If a window is 
associated with the device location being set 
the existing window is closed and a pointer 
Closed WINDOW_CONTROL_BLOCK is returned in 
Register. Otherwise 0000 is returned in 


Display 
already 
up, then 
to the 
the HL 
the HL 


Register. It should be noted that windows must not be 


re-defined in both foreground and background 


tasks at 


the same time because the routine is not re-entrant. 


Spec. 
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RETURN GLOBAL ADDRESS OF BOS ROUTINE 


The following BOS routines have globally known entry 


points: 

Name Description Reference No. 
WINDO Open window 1 
CLOSEW Close window 2 
SETCU Set cursor parameters 3 
GOTOX Move cursor in window 4 
PUTCH Put character into window 5 
UPSCR Scroll window up one row 6 
DOWNS Scroll window down one row 7 
LEFTS Scroll window left one column 8 
RIGHT Scroll window right one column 9 
FILLA Fill area of window 10 
DUMBT Use window as dumb terminal 11 


See section 5.2.4 for complete details on using DOS 
call 99H. 


INPUT STATUS FROM VIDEO SCREEN WINDOW 


In keeping with the standard for physical device 


drivers, two entry points are provided for the Video & 
Screen Device Drivers. The first of these is as 

follows: 

VIDEO_SCREEN: DEVICE_READY (call number A2H) 


Function: Returns a data ready indication for a 
specified window 


Entry Parameters: Register C = A2 Hex 
Register E = Window Number 
Where: 
Window Number has a range 
of 1 to 5. 
Exit Parameters: Register A = Return Code 
Where: 


Return Code = 0 indicates 
that the window is 
undefined. 

Return Code = non-zero 
indicates that the 
window is defined 
and ready to accept 
data. 
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OUTPUT DATA TO VIDEO SCREEN WINDOW 


The second of the screen drivers has the following 
format: 


VIDEO_SCREEN: SEND_DATA (call number A3H) 


Function: Writes a character to the specified window 


Entry Parameters: Register C = A3 Hex 
Register E = Window Number 
Where: 
Window Number has a range 


of 1 to 5. 
Register D = ASCII Character to be 
sent to video screen 


Exit Parameters: Register A = Return Code 
Where: 

Return Code = 0 indicates 
that the window is 
undefined and data 
was not sent. 

Return Code = non-zero 
indicates that the 
window is defined 
and data was sent. 


For a list of the control characters which are 


accepted by this driver, see the section on BOS call 
DUMBT. 
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5.4.7 BOS CALL INTERFACE 


This XIOS module contains eleven low-level BOS routines 


for using windows. Linkage to these routines is direct 
with their addresses being resolved with DOS call 99H as 
described in section 3.5.5.6.2 


OPEN A WINDOW 
ROUTINE NAME: WINDO 
GLOBAL REFERENCE NUMBER: 1 
FUNCTION: Open a window 
ENTRY PARAMETERS: REGISTER BC = Pointer to a valid 


WINDOW_CONTROL- BLOCK 
Where: 


WINDOW_CONTROL_BLOCK contains: 
TOP_LEFT_ADDRESS: WORD; 


COLUMN_WIDTH : BYTE; 
ROW_DEPTH: BYTE; 
CURSOR_TYPE: BYTE; 
CURSOR_PATTERN: BYTE; 
CURSOR_X_POS: BYTE; 
CURSOR_Y_POS: BYTE; 
TAB_MAP: ARRAY[1..39] OF 


BOOLEAN; 
Where: 
TOP_LEFT_ADDRESS contains a two byte value. 
This value is computed as follows: 
TOP_LEFT_ADDRESS = row number * 40 
+ column number 
Where: the row number and column 
number represent the top 
left corner of the window 
This value has a range of 0 to 959 
decimal 
COLUMN_WIDTH contains a one byte value. It 
is the number of columns the window is 
wide. It has a range of 1 to 40. 
ROW_DEPTH contains a one byte value. It is 
the number of rows the window is deep. 
It has a range of 1 to 24. 
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CURSOR_TYPE contains a one byte value. Two 
bits are defined as follows: 
bit OQ set indicates a visible cursor 


exists 

bit 0 clear indicates no visible cursor 
exists 

bit 7 set indicates the cursor is to 
flash 

bit 7 clear indicates the cursor is to 
be steady 


PATTERN_NAME contains a one byte value. It 
is the ASCII character which is to be 
the cursor shape. The default window 
uses the underline character. 

CURSOR_X_POS contains a one byte value. It 
is the relative cursor column position 
within the window. It has a range of 0 
to COLUMN_WIDTH-1. [It is usually set to 
0 


CURSOR_Y_POS contains a one byte value. It 
is the relative cursor row position 
within the window. It has a range of 0 
to ROW_DEPTH-1. It is usually set to 0. 

TAB_MAP contains an array of 40 bits (5 
bytes). These bits identify tab stops. 
If a bit is set, then a tab stop exists 
at that relative column number in the 
window. 


EXIT PARAMETERS: REGISTER A = RETURN CODE 


Where: 
RETURN CODE = 255 indicates 
that the Open was 
successful 


RETURN CODE = 0 indicates that 
the Open failed due to it 
being the sixth window or 
window control block not 
specified correctly 


CAUTIONS: This routine is not re~entrant 


REGISTERS USED: A,B,C,D,E,F,HL,IX 
6+ Bytes of stack used 


This routine is used to open a window on the’ screen 
and initialize a cursor in the window. It is passed a 
properly set up WINDOW_CONTROL_BLOCK. A maximum of 5 
windows may be defined concurrently. If the 
WINDOW_CONTROL_BLOCK is not set up correctly or the 
6th window is to be opened, the return code is zero. 
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CLOSE WINDOW 

ROUTINE NAME: CLOSEW 

GLOBAL REFERENCE NUMBER: 2 
FUNCTION: Close an opened window 


ENTRY PARAMETERS: REGISTER BC = Pointer to 
WINDOW_CONTROL_BLOCK 
to be closed 
Tf BC = 0 then all previously 
opened windows are closed 


EXIT PARAMETERS: REGISTER A = RETURN CODE 
Where: 

RETURN CODE = 0 indicates that 
WCB was not found in 
table of open windows 

RETURN CODE = 255 indicates 
that the window was 
successfully closed 


CAUTIONS: This routine is not re-entrant 


REGISTERS USED: A,B,C,D,E,F,HL,IX 
4+ Bytes of stack used 


This routine is used to close a cursor window when it 
is no longer needed. A pointer to the 
WINDOW_CONTROL_BLOCK is passed in register BC. The WCB 
is removed from the list of active windows, and the 
window cursor is turned off. 


SET CURSOR PARAMETERS 

ROUTINE NAME: SETCU 

GLOBAL REFERENCE NUMBER: 3 

FUNCTION: Set the cursor parameters 


ENTRY PARAMETERS: REGISTER BC = Pointer to a working 
Window Control Block 
CURSOR_TYPE 


REGISTER D 
E PATTERN_NAME 


REGISTER 
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Where: 
CURSOR_TYPE contains a one byte value. Two 
bits are defined as follows: 
bit 0 set indicates a visible cursor 


exists 

bit 0 clear indicates no visible cursor 
exists 

bit 7 set indicates the cursor is to 
flash 

bit 7 clear indicates the cursor is to 
be steady 


PATTERN_NAME contains a one byte value. It 
is the ASCII character which is to be 
the cursor shape. The default window 
uses the underline character. 


EXIT PARAMETERS: REGISTER A = RETURN CODE 
Where: 
RETURN CODE = 0 indicates that 
WCB was not found in 
table of open windows 
RETURN CODE = 255 indicates 
that the change occurred. 


CAUTIONS: This routine is not re~entrant 


REGISTERS USED: A,B,C,D,E,F,HL,IX 
6+ Bytes of stack used 


This routine is used to alter the parameters of a 
cursor in a cursor window which is already open. This 
routine MUST be used to turn off and turn on cursor 
flashing for windows. 

MOVE CURSOR IN WINDOW 

ROUTINE NAME: GOTOX 

GLOBAL REFERENCE NUMBER: 4 


FUNCTION: Move the cursor to new position 


ENTRY PARAMETERS: REGISTER BC Pointer to an opened 
Window Control Block 
REGISTER D = CURSOR_X_POS 


REGISTER E CURSOR_Y_POS 


Spec. 
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Where: 

CURSOR_X_POS contains a one byte value. It 
is the relative cursor column position 
within the window. It has a range of 0 
to COLUMN_WIDTH-1. It is usually set to 
0. 

CURSOR_Y_POS contains a one byte value. It 
is the relative cursor row position 
within the window. It has a range of 0 
to ROW_DEPTH-1. It is usually set to 0. 


EXIT PARAMETERS: REGISTER A = RETURN CODE 
Where: 

RETURN CODE = 0 indicates that 
the reposition failed due 
to an incorrectly 
specified window. 

RETURN CODE = 255 indicates 
that the reposition 
occurred, 


CAUTIONS: This routine is not re-entrant 


REGISTERS USED: A,B,C,D,E,F,HL,IX 
4+ Bytes of stack used 


This routine is used to re-position the cursor in a 

window. If the cursor is positioned outside the window 

the return code will indicate failure. 

PUT CHARACTER IN WINDOW 

ROUTINE NAME: PUTCH 

GLOBAL REFERENCE NUMBER: 5 

FUNCTION: Put an ASCII character in the window 

ENTRY PARAMETERS: REGISTER BC = Pointer to an opened 
Window control block 


REGISTER E = ASCII character with 
range 20H to 7EH 
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EXIT PARAMETERS: REGISTER A = RETURN CODE 
Where: 

RETURN CODE = 0 indicates that 
write to the window 
failed due to the window 
not being opened or the 


Window Control Block 
being incorrectly 
specified. 


RETURN CODE = 255 indicates 
that the write to the 
window was successful. 


CAUTIONS: This routine is not re-entrant 


REGISTERS USED: A,B,C,D,E,F,HL,;IX 
6+ Bytes of stack used 


This routine will output a single character at the 
current cursor position and advance the cursor. No 
control characters are interpreted, any data passed to 
the routine is assumed to be a character. The cursor 
is advanced according to the WRAP Algorithm as 
follows: 


CURSOR. XPOS: =CURSOR. XPOS+1; 
IF CURSOR.XPOS > (WINDOW.WIDTH - 1) THEN 
BEGIN 
CURSOR. XPOS:=0; 
CURSOR. YPOS: =CURSOR. YPOS+1; 
END 
ELSE IF CURSOR.XPOS < 0 THEN 
BEGIN 
CURSOR. XPOS: =WINDOW.WIDTH-1; 
CURSOR. YPOS:=CURSOR. YPOS-1; 
END 
IF CURSOR.YPOS > (WINDOW.ROWDEPTH-1) THEN 
BEGIN 
CURSOR. YPOS:=0; 
EXIT (WRAP_ALGORITHM) ; 
END; 
IF CURSOR. YPOS < 0 THEN 
BEGIN 
CURSOR. YPOS: =WINDOW. ROWDEPTH-1; 
EXIT (WRAP_ALGORITHM; 
END; 
EXIT (WRAP_ALGORITHM) ; 
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SCROLL WINDOW UP ONE ROW 

ROUTINE NAME: UPSCR 

GLOBAL REFERENCE NUMBER: 6 

FUNCTION: Scroll the window up one line or row 


ENTRY PARAMETERS: REGISTER BC = Pointer to a complete 
Or partial WINDOW_CONTROL_BLOCK 
Where: 
WINDOW_CONTROL_BLOCK must contain valid 
values for the following: 
TOP_LEFT_ADDRESS: WORD; 
COLUMN_WIDTH: BYTE; 
ROW_DEPTH : BYTE; 
Where: 
TOP_LEFT_ADDRESS contains a two byte value. 
This value is computed as follows: 
TOP_LEFT_ADDRESS = row number * 40 
+ column number 
Where: the row number and column 
number represent the top 
left corner of the window 
This value has a range of 0 to 959 
decimal 
COLUMN_WIDTH contains a one byte value. It 
is the number of columns the window is 
wide. It has a range of 1 to 40. 
ROW_DEPTH contains a one byte value. It is 
the number of rows the window is deep. 
It has a range of 1 to 24. 


EXIT PARAMETERS: REGISTER A = RETURN CODE 
Where: 

RETURN CODE = 255 indicates 
that the scroll was 
successful 

RETURN CODE = 0 indicates that 
the scroll failed due to 
window control block not 
specified correctly 


CAUTIONS: This routine is not re-entrant 
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REGISTERS USED: A,B,C,D,E,F,HL,IX 
8+ Bytes of stack used 


This routine will scroll a window up one row and 
replace the bottom row with blanks. Note that the area 
being scrolled need not be an open window. A partial 
WINDOW_CONTROL_BLOCK may be used to define the area to 
be scrolled. 


SCROLL WINDOW DOWN ONE ROW 

ROUTINE NAME: DOWNS 

GLOBAL REFERENCE NUMBER: 7 

FUNCTION: Scroll the window down one line or row 


ENTRY PARAMETERS: REGISTER BC = Pointer to a complete 
or partial WINDOW_CONTROL_BLOCK 
Where: 
WINDOW_CONTROL_BLOCK must contain valid 
values for the following: 
TOP_LEFT_ADDRESS: WORD; 
COLUMN_WIDTH: BYTE; 
ROW_DEPTH: BYTE; 
Where: 
TOP_LEFT_ADDRESS contains a two byte value. 
This value is computed as follows: 
TOP_LEFT_ADDRESS = row number * 40 
+ column number 
Where: the row number and column 
number represent the top 
left corner of the window 
This value has a range of 0 to 959 
decimal 
COLUMN_WIDTH contains a one byte value. It 
is the number of columns the window is 
wide. It has a range of 1 to 40. 
ROW_DEPTH contains a one byte value. It is 
the number of rows the window is deep. 
It has a range of 1 to 24. 
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EXIT PARAMETERS: REGISTER A = RETURN CODE 
Where: 

RETURN CODE = 255 indicates 
that the scroll was 
successful 

RETURN CODE = 0 indicates that 
the scroll failed due to 
window control block not 
specified correctly 


CAUTIONS: This routine is not re-entrant 


REGISTERS USED: A,B,C,D,E,F,HL,1IX 
8+ Bytes of stack used 


This routine will scroll a window down one row and 
replace the top row with blanks. Note that the area 
being scrolled need not be an open window. A partial 
WINDOW_CONTROL_BLOCK may be used to define the area to 
be scrolled. 


SCROLL WINDOW LEFT ONE COLUMN 

ROUTINE NAME: LEFTS 

GLOBAL REFERENCE NUMBER: 8 

FUNCTION: Scroll the window left one column 


ENTRY PARAMETERS: REGISTER BC = Pointer to a complete 
or partial WINDOW_CONTROL_BLOCK 
Wheres 
WINDOW_CONTROL_BLOCK must contain valid 
values for the following: 
TOP_LEFT_ADDRESS: WORD; 
COLUMN_WIDTH: BYTE; 
ROW_DEPTH: BYTE; 
Where: 
TOP_LEFT_ADDRESS contains a two byte value. 
This value is computed as follows: 
TOP_LEFT_ ADDRESS = row number * 40 
+ column number 
Where: the row number and column 
number represent the top 
left corner of the window 
This value has a range of 0 to 959 
decimal 
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COLUMN_WIDTH contains a one byte value. It 
is the number of columns the window is 
wide. It has a range of 1 to 40. 

ROW_DEPTH contains a one byte value. It is 
the number of rows the window is deep. 
It has a range of 1 to 24. 


EXIT PARAMETERS: REGISTER A = RETURN CODE 
Where: 

RETURN CODE = 255 indicates 
that the scroll was 
successful 

RETURN CODE = 0 indicates that 
the scroll failed due to 
window control block not 
specified correctly 


CAUTIONS: This routine is not re-entrant 


REGISTERS USED: A,B,C,D,E,F,HL,IX 
8+ Bytes of stack used 


This routine will scroll a window left one column and 
replace the last column with blanks. Note that the 
area being scrolled need not be an open window. A 
partial WINDOW_CONTROL_BLOCK may be used to define the 
area to be scrolled. 


SCROLL WINDOW RIGHT ONE COLUMN 

ROUTINE NAME: RIGHT 

GLOBAL REFERENCE NUMBER: 9 

FUNCTION: Scroll the window right one column 


ENTRY PARAMETERS: REGISTER BC = Pointer to a complete 
Or partial WINDOW_CONTROL_BLOCK 
Where: 
WINDOW_CONTROL_BLOCK must contain valid 
values for the following: 
TOP_LEFT_ADDRESS: WORD; 
COLUMN_WIDTH: BYTE; 
ROW_DEPTH : BYTE; 
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Where: 
TOP_LEFT_ADDRESS contains a two byte value. 
This value is computed as follows: 
TOP_LEFT_ADDRESS = row number * 40 
+ column number 
Where: the row number and column 
number represent the top 
left corner of the window 
This value has a range of 0 to 959 
decimal 
COLUMN_WIDTH contains a one byte value. It 
is the number of columns the window is 
wide. It has a range of 1 to 40. 
ROW_DEPTH contains a one byte value. It is 
the number of rows the window is deep. 
It has a range of 1 to 24. 


EXIT PARAMETERS: REGISTER A = RETURN CODE 
Where: 

RETURN CODE = 255 indicates 
that the scroll was 
successful 

RETURN CODE = 0 indicates that 
the scroll failed due to 
window control block not 
specified correctly 


CAUTIONS: This routine is not re-entrant 


REGISTERS USED: A,B,C,D,E,F,HL,IX 
8+ Bytes of stack used 


This routine will scroll a window right one column and 
replace the first column with blanks. Note that the 
area being scrolled need not be an open window. A 
partial WINDOW_CONTROL_BLOCK may be used to define the 
area to be scrolled. 


FILL AREA OF WINDOW 
ROUTINE NAME: FILLA 
GLOBAL REFERENCE NUMBER: 10 
FUNCTION: Fill the entire area of a window 
ENTRY PARAMETERS: REGISTER E& = ASCII character 
with range 20H to 7EH 


REGISTER BC = Pointer to a complete 
or partial WINDOW_CONTROL_BLOCK 
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Where: - : 
WINDOW_CONTROL_BLOCK must contain valid 
a values for the following: 
TOP_LEFT_ADDRESS: WORD; 
COLUMN_WIDTH: BYTE; 
ROW_DEPTH: BYTE; 
Where: 
TOP_LEFT_ADDRESS contains a two byte value. 
This value is computed as follows: 
TOP_LEFT_ADDRESS = row number * 40 
+ column number 
Where: the row number and column 
number represent the top 
left corner of the window 
This value has a range of 0 to 959 
decimal 
COLUMN_WIDTH contains a one byte value. It 
is the number of columns the window is 
wide. It has a range of 1 to 40. 
ROW_DEPTH contains a one byte value. It is 
the number of rows the window is deep. 
It has a range of 1 to 24, 


EXIT PARAMETERS: REGISTER A = RETURN CODE 
Where: 

RETURN CODE = 255 indicates 
that the fill was 
successful 

RETURN CODE = 0 indicates that 
the fill failed due to 
window control block not 
specified correctly 


CAUTIONS: This routine is not re-entrant 


REGISTERS USED: A,B,C,D,E,F,HL,IX 
8+ Bytes of stack used 


This routine will fill a rectangular area on the 
screen with a particular character. The area being 
filled need not be an open window. A partial 
WINDOW_CONTROL_BLOCK may be used to specify the area 
to be filled. 
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USE WINDOW AS DUMB TERMINAL 
ROUTINE NAME: DUMBT 
GLOBAL REFERENCE NUMBER: 11 


FUNCTION: Use a window as a dumb terminal or glass 
teletype 


ENTRY PARAMETERS: REGISTER E = ASCII character 
with range 0 to 7FH 
REGISTER BC = Pointer to a complete 
WINDOW_CONTROL_BLOCK 


EXIT PARAMETERS: REGISTER A = RETURN CODE 


Where: 
RETURN CODE = 255 indicates 
that the write was 
successful 


RETURN CODE = 0 indicates that 
the window is not open. 


CAUTIONS: This routine is not re-entrant 


REGISTERS USED: A,B,C,D,E,F,HL,1IX 
6+ Bytes of stack used r 


This routine allows an opened window to be used as if 
it were an ASCII terminal. It will handle control 
characters: Carriage return, line feed, delete, 
backspace, form feed, and horizontal tabs. The 
routine puts the character at the current cursor 
position of an opened window. It will interpret the 
control characters as follows: 


LINE FEED: CONTROL J 

If the cursor is on the bottom line of the window, the 
window will scroll up one line and leave the bottom 
line filled with SPACES and the cursor will drop 
Straight down into this blank line. If the cursor is 
in the middle of the window, the cursor just drops 
down one line. 


CARRIAGE RETURN: CONTROL M 


The cursor will move to the first position of the 
current line. 
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BACKSPACE: CONTROL H 


The cursor moves back one position. If the cursor is 
in the top-left position of the window, nothing 
happens. 


DELETE: 7FH 
The cursor backspaces one character and places a SPACE 
over the character. 


FORM FEED: CONTROL L 
The cursor is reset to the top-left position of the 
window and the window is filled with SPACES. 


HORIZONTAL TAB: CONTROL I 

The cursor is moved over to the next tab position of 
the current line. If no tab position is found, the 
cursor is placed at the start of the next line. 


BELL: CONTROL G 
A short tone will sound. 


VERTICAL TAB: CONTROL K 
The cursor moves up one line. If the cursor is on the 
top-most line, nothing will happen. 


HOME: CONTROL ~* 
The cursor is reset to the top-left position of the 
window. 


OTHER CONTROL CHARACTERS: 
Nothing will happen. 
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5.5 80 COLUMN SCREEN DRIVER 
5.5.1 INTRODUCTION 


This XI0S module will contain a complete set of routines 
which form the 80 column screen driver. This screen 
@river will emulate a Lear Seigler ADM-3A type terminal 
on a 36 column visual video screen. A list of the 
control character implemented is specified in a later 
section. 


5.5.2 OPERATIONAL REQUIREMENTS 


This XIOS module will not require any other XIOS module 
in order for it to function. It does however use BOS 
calls from within the IOS Kernel to interface with the 
video hardware. 


5.5.3 MODULE SPECIFIC ERROR CODES 


This XIOS module will not return any error codes 
specific to itself, when it has been loaded, and when 
the module has finished initialization or de- 
initialization. 


5.5.4 MODULE INITIALIZATION 


When this XIOS module is loaded, its initialization 
procedure is executed. This procedure will do the 
following: 


1. Link into the IOS Kernel BOS routines as 
required. 

2- Disable the previous screen driver. 

3. Set the video screen to text mode. 

4. Fill the video screen with a blue background 
and a blue foreground. 

5. Create a virtual screen with size 80 columns by 
24 rows; the cursor will be a flashing 
underline character. 

6. Create a visual "window" with size 36 columns 
by 24 rows. 

7. Enable the video hardware to output to screen. 

8. Enable the cursor to flash. 


Spec. 50-90020490 Page 7 ~ l June 8, 1984 


XIOS - 80 COLUMN SCREEN DRIVER 


5.5.5 MODULE DE-INITIALIZATION 


Prior to the module being physically remov 
memory, a "shut-down" or de-initialization proc 
executed. This procedure will do the following: 


1. Clear the screen by filling with blanks 
2. Restore the Kernel routines such as th 
interrupt handler, to their "prior 
module" state. 
This procedure can not and will not restore th 
context of the screen prior to the XIOS modul 
loaded. 
5.5.6 DOS CALL INTERFACE 


This module will be capable of decoding and e 
two DOS calls. The call numbers decoded are: 


A2 -~ INPUT STATUS FROM VIDEO SCREEN 
A3 ~- OUTPUT DATA TO VIDEO SCREEN 


5.5.6.1 INPUT STATUS FROM VIDEO SCREEN WINDOW 


In keeping with the standard for physical 


drivers, two entry points are provided for th 
Screen Device Drivers. The first of these 
follows: 

VIDEO_SCREEN: DEVICE_READY {call num 


Function: Returns a data ready indication 
screen driver 


Entry Parameters: Register C = A2 Hex 


Exit Parameters: Register A = Return Code 
Where: 


ed from 
edure is 


e clock 
to xXIOS 


e total 
e being 


xecuting 


device 
e Video 
is as 
ber A2H) 


for the 


Return Code = 0 indicates 


that the 

device is bu 
Return Code = 

indicates t 


video dev 
ready to 
data. 
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5.5.6.2 OUTPUT DATA TO VIDEO SCREEN WINDOW 
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The second of the screen drivers has the following 
format: 


VIDEO_SCREEN: SEND_DATA (call number A3H) 
Function: Writes a character to the screen driver. 


A3 Hex 
ASCII Character to be 
sent to video screen 


Entry Parameters: Register C 
Register D 


Exit Parameters: None 


The following is a list of the control characters 
interpreted: 


BELL: CONTROL G 
A short tone will sound. 


BACKSPACE: CONTROL H 

The cursor moves back one position. If the cursor is 
in the top-left position of the screen, nothing 
happens. 


LINE FEED: CONTROL J 

If the cursor is on the bottom line of the screen, the 
screen will scroll up one line and leave the bottom 
line filled with SPACES and the cursor will drop 
straight down into this blank line. If the cursor is 
in the middle of the screen, the cursor just drops 
down one line. 


CURSOR UP: CONTROL K 
The cursor moves up one line. If the cursor is on the 
top-most line, nothing will happen. 


CURSOR RIGHT: CONTROL L 

The cursor moves right one column. If the cursor is 
at the right most position on a line, a line feed 
action will occur 


CARRIAGE RETURN: CONTROL M 
The cursor will move to the first position of the 
current line. 
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CLEAR SCREEN: CONTROL Z 


The cursor is reset to the top-left position af #ha 
screen and the screen is filled with SPACES. 


HOME: CONTROL ~ 
The cursor is reset to the top-left position of the 
screen. : 


DELETE: 7FH 
The cursor backspaces one character and places a SPACE 
over the character. 


OTHER CONTROL CHARACTERS: 
Nothing will happen. 
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5.6 CP/M COMPATIBLE LOGICAL DEVICE DRIVERS 


5.6.1 


5.6.2 


5.6.3 


5.6.4 


5.6.5 
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INTRODUCTION 


This XIOS module will contain a set of routines which 
are compatible with the logical device drivers found in 
CP/M 2.2. This is a subset of the CP/M 2.2 BDOS and 
does not include the disk oriented functions. These 
routines were formerly contained within the IOS Kernel. 


OPERATIONAL REQUIREMENTS 


This XIOS module may require other XIOS modules in order 
for it to function. It does use DOS calls OAOH through 
QA5H inclusively for interfacing to the screen, the 
keyboard, and the printer. These DOS calls will be 
found within the IOS KERNEL or XIOS modules. The user 
must ensure that the functions for DOS calls OAOH to 
OA5SH exist in memory, prior to uSing the logical 
drivers. 


MODULE SPECIFIC ERROR CODES 


This XIOS module will not return any error codes 
specific to itself, when it has been loaded, and when 
the module has finished initialization or de- 
initialization. 


MODULE INITIALIZATION 


When this XIOS module is loaded, its initialization 
procedure is executed. This procedure will do the 
following: 


1. Resolve the required global references in the 
IOS KERNEL. 

2. Modify the jump address at location 1,2 in RAM 
such that it points to the second entry in the 
BIOS jump table (as per CP/M convention). 


MODULE DE~INITIALIZATION 

Prior to the module being physically removed from 
memory, a "shut-down" or de-initialization procedure is 
executed. This procedure will do the following: 


1. Replace the modified jump location at 1,2 in 
RAM with that which was originally there. 
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5.6.6 DOS CALL INTERFACE 


This module will be capable of decoding and executing 
ten DOS calls. The call numbers decoded are: 


_ 00 -~ SYSTEM RESET 
01 -- CONSOLE INPUT 
02 -~ CONSOLE OUTPUT 
03 -- READER INPUT 
04 -~ TAPE OUTPUT 
05 -~ LIST OUTPUT 
06 -- DIRECT CONSOLE 1/0 
09 -- PRINT STRING 
10 -- READ CONSOLE BUFFER 
1l -- GET CONSOLE STATUS 


SYSTEM_RESET (call number 00H) 
-performs same function as a jump to location 0000 Hex 
-entry parameters: 
C Register: 00 Hex 
-is not re-entrant 


CONSOLE_INPUT (call number 01H) 

-reads the next character from the logical console with 
echo. The call does not return until a character is ready. 
This call will only accept CP/M compatible ASCII 
characters. If the "YES" key is hit, a "Y" is returned. If 
the "NO" key is hit, a "N" is returned. All other key 
codes above 7FH are returned but not echoed to the screen. 

~entry parameters: 

C Register: 01 Hex 

-Returned Values: 

A Register: Character Input 
~is not re-entrant 


CONSOLE_OUT PUT (call number 02H) 

-outputs a character to the logical console. Since the 
default physical console driver is DOS calls 0A2H and 0A3H, 
consult the specification for DOS call QA3H for control 
character interpretation. 

-entry parameters: 

C Register: 02 Hex 
E Register: Character to be output 
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READER_INPUT (call number 03H) 

-get a byte from the logical TAPE reader. Control will not 
return to the calling program until the character has been 
read. This call will only accept CP/M compatible ASCII 
characters. If the "YES" key is hit, a "Y" is returned. If 
the "NO" key is hit, a "N" is returned. All other key 
codes above 7FH are returned but not echoed to the screen. 

~entry parameters: 

C Register: 03 Hex 

-returned value: 

A Register: character read 

-is not re-entrant 


PUNCH_OUTPUT (call number 048) 

-output a byte to the logical TAPE punch. Since the default 
physical console driver is DOS calls O0A2H and OA3H, consult 
the specification for DOS call 0OA3H for control character 
interpretation. 


-entry parameters: 
C Register: 04 Hex 
E Register: character to be output 


LIST_OUTPUT (call number 05H) 
-output a character to the logical list device 
~entry parameters: 
C Register: 05 Hex 
E Register: character to be output 


DIRECT_CONSOLE_I0 (call number 06H) 

-provides unadorned I/O from/to the logical console. Upon 
entry, the E register either contains an OFF Hex, denoting 
a console input request, or a character to be output. If 
the input value if OFF Hex, then the functions returns with 
the A register set to 00 if no character is ready at the 
logical console otherwise the A register is set to the 
character value input from the logical console. This call 
will only accept CP/M compatible ASCII characters. If the 
"YES" key is hit, a "Y" is returned. If the "NO" key is 
hit, a "N" is returned. Since the default physical console 
driver is DOS calls OA2H and OA3H, consult the 
specification for DOS call OA3H for control character 
interpretation. 
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-entry parameters: 
C Register: 06 Hex 
E Register: FF Hex (input) or 
character to be cutput 
-returned value: 
A Register: character of 00 Hex (input) 
nothing if output 
-is not re-entrant 


PRINT_STRING (call number 09H) 

-print a string to the logical console from a buffer. The 
character string stored in memory at the location pointed 
to by the DE register is sent to the logical console. A '$' 
is used as a delimiter to end the print string. Since the 
default physical console driver is DOS calls 0A2H and 0OA3H, 
consult the specification for DOS call OA3H for control 
character interpretation. 


-entry parameters: 
C Register: 09 Hex 
DE Register: pointer to string 


READ_CONSOLE_BUFFER (call number OAH) 
-read a line of edited logical console input to a buffer. 
The input is stored in the memory buffer pointer to by the 
DE register. If the buffer overflows console input is 
terminated. The format of the buffer is: 


MAX_BUF_SIZE: BYTE; 
NUMBER_OF_CHARACTERS_READ: BYTE; 
CHARACTER_BUFFER: ARRAY[1..MAX_BUF_SIZE] BYTE; 


The "GO" key (OD Hex) or CNTRL J (OA Hex) will terminate 
the input line. This call will only accept CP/M compatible 
ASCII characters. If the "YES" key is hit, a "Y" is 
returned. If the "NO" key is hit, a "N" is returned. All 
other key codes above 7FH are returned but not echoed to 
the screen. 
-entry parameters: 

C Register: OA Hex 

DE Register: Pointer to MAX_BUF_SIZE 

(MAX_BUF_SIZE must be set as well) 

~returned values: 

Console Characters in Buffer 

NUMBER_OF_CHARACTERS_READ set 
-is not re-entrant — 
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GET-CONSOLE_STATUS (call number OBH) 

-check to see if character has been typed at logical console 
-entry parameters: 

C Register: OB Hex 
~returned value: 

A Register: 00 Hex -No character ready 

FF Hex ~Character is ready and waiting 

-is not re-entrant 


For more information on CP/M please refer to reference 
[10]. Also note some important information in section 1 
concerning CP/M implementation and upgrading in the IOS. 
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APPENDIX A 


Definiti ana at satio 


ASCII 


BASIC 


BDOS 


BIOS 


Boot ROM 


BOS 


CATV 


HEAD-END 


I/F 
I/O 


IOBYTE 


Tos 


ISR 


LED 


An American standard for assigning code numbers to 
keyboard characters 


A commonly used computer language on personal computers 


Digital Research's Basic Diskette Operating System 
This forms part of CP/M 


Basic Input and Output Handlers 


Read Only Memory which is immediately executed after a 
NPC is powered up 


Basic Operating System ~ Low level routines 


Community Antenna Television System ~- It is now used to 
denote any cable television system 


Digital Research's Diskette Operating System - It is 
the abreviation for control processor and monitor 


Canadian Standards Association 

General abreviation for diskette operating system - 
however for the NPC it means Downloadable Operating 
System 


Refers to the central minicomputer system that broad- 
casts the software. 


General abreviation for interface 
General Abreviation for input and output 


A memory location used by CP/M to indicate what physical 
I/O is connected to which logical 1/0 


Internal Operating Software for the NABU Personal 
Computer 


General abreviation for Interrupt Service Routine 


Light Emitting Diode used on front panel of NPC for 
indicating partial status of the NPC 
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NA 


NNI 
NPC 
PIXEL 


RAM 


APPENDICES 


NABU Adaptor - It is the unit which interfaces the NPC 
to a CATV cable system which broadcasts software and 
data for use in a NPC. It was formerly called NNI 

NABU Network Interface ~ It is the old name for NA. 
NABU Personal Computer 

The smallest addressable graphics unit on a TV screen. 


Read and Write type Memory for computers 


RF Modulator 


ROM 


SPRITE 


SYM 


TMS-9918A 
VDP 


That piece of electronic equipment which converts the 
digital signals of the head-end minicomputer into ana- 
log signals for broadcasting. 

Read Only type Memory for computers 


A single-coloured, moveable, positionable graphics 
entity with variable pixel definition and resolution. 


It is a special key on the NPC keyboard which can be 
used to redefine the keyboard 


The name for the video chip in the NPC 


Video display processor - for the NPC it is the TMS- 
9918A 
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This is a summary of the complete set of current IOS functions. 
For the CP/M calls and DOS calis, the number directly preceeding 
each function is the value register C must contain prior to the 
call. For the BOS calls the number is the value that the link 
table must be initialized to in order to gain access to the 
proper routine. 


CP/M (Calls to location 0005H) 


00 System Reset Resets NPC 

ol Console Input Read data from console 
02 Console Output Type data to console 

03 Reader Input Read data from paper tape 
04 Punch Output Punch data on paper tape 
05 List Output List data to printer 

06 Direct Console I/0 Unadorned console I/0 

09 Print String Print message in buffer 
OA Read Console Buffer Read message in buffer 
OB Get Console Status Return status of console 
oc Get Version Number Not Implemented 


Downloadable Operating Software (DOS) (Calls to location 00088) 


Segment Routines 


80 Reset Device Reset logical device 

82 Get Status Get adaptor status 

83 Set Status Set adaptor status 

84 Load Segment Load segment from cable 

87 SEGSCST Base Address Return control status block 


88 Directory Search 

96 Load XIOS Module 

97 Unload XIOS Module 

99 Resolve Global Reference 


I/O Service Routines 


8A I/O Router: Attach Set phys dev to log dev 
AO Human Input: Device Ready Keyboard ready 

Al Human Input: Get Data Get keyboard data 

A2 Video Screen: Device Ready Screen ready 

A3 Video Screen: Send Data Send data to screen 

A4 Printer: Device Ready Printer ready 

A5 Printer: Send Data Send printer data 
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Multitasking Routines 


8B Clock User: Task Attach Attach task to system clk 

8c Clock User: Task Remove Remove task 

8D Device User: Task Attach Attach device to clk 

8E Device User: Task Remove Remove device from clk 
Miscellaneous 

90 Link BOS Routines Set up linktable for BOS 

91 Set SYM key Table Redefinition table for SYM 

92 Read Real Time Clock 

93 Set Real Time Clock 

94 Configuration Return system configuration 


Basic Operating Software (BOS) (Called via link table) 


Video Routines 


VREGRD 
VTABRD 
VREGWR 
VSTATRD 
VNAMEST 
VCOLRST 
VPTRNST 
VATRIST 
VSPRIST 
VBLKON 
VBLKOFF 
VRAMRD 
VRAMWR 
FASTL8 
FASTLD 
FASTD8 
FASTDU 
VRAML8 
VRAMLD 
VRAMD8 
VRAMDU 
SPMARK 
SPMOVE 
SPCOLR 
SPNAME 
RPATRN 
LPATRN 


Reads TMS~9918A video display register 
Reads current table base address ptrs 
Writes video display register 

Reads video status register 

Sets the pattern name address 

Sets the colour table address 

Sets the pattern table address 

Sets the sprite attributes table addr 
Sets the sprite table address 

Blanks the video display 

Turns on the video display 

Reads a single byte of VRAM 

Writes a single byte of VRAM 

Write a string (256 max) of bytes to VRAM 
Write a string (16 K max) of bytes to VRAM 
Read string of bytes (256 max) from VRAM 
Read string of bytes (16 K max) from VRAM 
Same as FASTL8 but interrupt protected 
Same as FASTLD but interrupt protected 
Same as FASTD8 but interrupt protected 
Same as FASTDU but interrupt protected 
Mark end of a sprite attributes table 
Move a sprite on the video screen 

Set the colour of a sprite 

Set pattern name assoc. with a sprite 
Load pattern def'ns into Screen table 
Load pattern def'ns into VRAM 

Return VRAM addr for a certain pattern 
Fill block of VRAM with a character 
Return name tab addr for any XY loc 
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20 PUTPAT 
21 GETPAT 


22 SETMSG 
23 PUTMSG 
24 GETMSG 
25 VSETTXT 
26 VSETG1 
27 VSETG2 
28 VSETSPA 
3A VMOVI 
3B VMOVD 


3C FASTRD 
3D FASTWR 


Audio Routines 


35 AUDRD 
36 AUDWR 


APPENDICES 


Put 
Get 
Set 
Put 
Get 
Set 
Set 
Set 
Set 


pattern at any XY loc 
pattern from any XY loc 

up screen message 

a message on screen 

a message from screen 

video for text mode 

video for Graphics 1 mode 
video for Graphics 2 mode 
sprite size and magnification 


Move data in VRAM up quickly 

Move data in VRAM down quickly 
Unprotected single byte VRAM read 
Unprotected single byte VRAM write 


Read audio chip register 
Write the audio chip register 


Miscellaneous BOS Routines 


02 CRBEG 
03 CREND 
29 MUL88 
37 CLKPRM 
38 HOINIT 
39 CREGWR 
3E SETMSK 


Start of a critical region 


End 


of a critical region 


Multiply two eight bit values 

Control real time processing 

Initialize Ios 

Write to the control port 

Write hardware interrupt control register 
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APPENDIX C 


The following is a sample program to demonstrate the use of the 
video display processsor and the audio generator. This program 
assumes that the M80 assembler (copyright Microsoft) is used. 


The program will place messages on the screen, move a red 


circular or a blue square sprite around on the screen under the 
control of a joystick and a clock attach routine. 


KEKEKEKEKKEKKKKEEKEEKEEKEEREKREKEREEEEEEKEEKEEKEREKREEEEKEEEEKEEREREEKEKRKEEKEKEEEEKEE 


PROGRAM NAME: DEMO.MAC 


we Se se we Ne 


e 

; 

; 

? DESCRIPTION: DEMONSTRATION PROGRAM TO INTRODUCE 

? THE 9918A VIDEO DISPLAY PROCESSOR, AUDIO 
; GENERATOR and the IOS. 

; 
7 
; 


KHERKEKEKKKKEKEK EEE KEKE KEE KIER EK EREER ERK KE REE KEKE EEE EE IRE EREKEKEKREEEERER 


~Z80 
»RADIX 10 7USE BASE 10 


;EXTERNAL FUNCTIONS 
7THESE LABELS REFERENCE CODE OUTSIDE OF THE MAIN PROGRAM. 


EXTRN TCHAR 7PATTERN DEFINITIONS 
EXTRN SPRPAT 7SPRITE PATTERN DEFINITIONS 
7 EQUATES 
BLACK EQU ol 
MGREEN EQU 02 
WHITE EQU OFH 
DBLUE EQU 


ZR RRR ER RE RKEREREEKEKE EKER EEE EKEEKKER ERE EEEEKREEREREEEKEKEKEA 
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+MACRO DEFINITIONS 


PCALL MACRO SUBR, PARM1, PARM2, PARM3 
IFNB <PARM1> 
LD BC, PARM1 
ENDIF 
IFNB <PARM2> 
LD DE, PARM2 
ENDIF 
IFNB <PARM3> 
LD HL, PARM3 
ENDIF 
CALL SUBR 
ENDM 
e 
DEFMSG MACRO XPOS, YPOS, MSG 
LOCAL END, START 
DB XPOS 
DB YPOS 
DB END~START 
START: DB MSG 
END: 
ENDM 
v 
SETCOLR MACRO BACK, TEXT 
IFB <TEXT> 
PCALL VREGWR, 07, 10H+BACK 
ELSE 
PCALL VREGWR, 07, TEXT*10H+BACK 
ENDIF 
ENDM 
‘ 
N.CLKAT MACRO TASKADR 
LD DE, TASKADR 
LD C,08BH 
CALL NABUSYS 
ENDM 
e 
N.CLKRV MACRO TASKADR 
LD DE, TASKADR 
LD C,08CH 
CALL NABUSYS 
ENDM 
’ 
N.LINKIO MACRO IOSPTR 
LD DE, IOSPTR 
LD C,090H 
CALL NABUSYS 
ENDM 
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; 
N. DEVRDY MACRO DEVICE, LOCATN 


LD E, LOCATN 
LD C, DEVICE*2+0A0H 
CALL NABUSYS 
ENDM 
‘ 
N.DEVIO MACRO DEVICE, LOCATN, DATA 
IFNB <DATA> 
LD A,DATA 
LD D,A 
ENDIF 
LD E,LOCATN 
LD C, DEVICE*2+0A1H 
CALL NABUSYS 
ENDM 


: 
e 
p RRR RARER ERIK KER ERE RR EERE RHEE KEEEER HERE EERE EEE EK KEERER ERE KER EKEREEKKRKEK 


7* DATA AREA * 
RR RRRK ARE KEK EEE ERE REE EERE REE EEE KER ER KEEREK KEE EREERE REE EERE EEEEEREEEKE 


7TASK CONTROL BLOCK FOR END OF PROGRAM 


TSKEND: : 
NEXT: DW 0 7;LINKED LIST POINTER 
ENDINT: DB 15 7EXECUTE TASK EVERY 1/4 SEC 
ENDINIT: DB 5H ;WAIT 5/60 SEC BEFORE EXECUTION 
ENDADR: DW 1H 7TASK ADDRESS 
7TASK CONTROL BLOCK FOR SPRITE MOVEMENT 
TSKMSP:: 
NEXT1: DW 1 s;NEXT TASK IN LINKED LIST 
SPINT: DB l ;EXECUTE TASK EVERY 1/60 OF A SECOND 
SPINTIT: DB l ;WAIT 1/60 OF A SEC BEFORE EXECUTION 
SPRADR: DW 1 3;TASK ADDRESS 
7DEFINE BYTES FOR VARIABLES 
X: DB i 7X POSITION OF SPRITE 
Ys DB 1 7Y POSITION OF SPRITE 
COLRR: DB 1 ;CURRENT COLOUR OF SPRITE 7=RED 8=CYAN 
OLDIR: DB 1 7OLD DIRECTION OF SPRITE 
XFLAG: DB 1 ;SOUND ENABLE FOR VERT. MOTION 1=ENABLED 
YFLAG : DB 1 7;SOUND ENABLE FOR HORIZ. MOTION 
CFLAG: DB 1 ;}COLOUR FLAG. PREVENTS RAPID COLOUR CHANGES 
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;DEFINE ALL THE MESSAGES TO BE PRINTED ® 


MSG1: DEFMSG 9H,3,'WELCOME TO NABU ' 

MSG2: DEFMSG 3H,11,'SAMPLE PROGRAM ' 

MSG3: DEFMSG 3H,13,'PRESS C KEY TO CONTINUE ' 
MSG4: DEFMSG 3H 14,'TO JOYSTICK PORTION OF TEST ' 
MSG5: DEFMSG 6H 18,'PRESS ESC KEY TO STOP ' 


g EERE KERE ER REE KE ERK KEKE REE EKER ER EKER EEE HK KER EE KERR ERE RRERKEREEREKEREKEEEEK 


3* START OF EXECUTION od 
fp RR RRR RE RRR RR ERK ER ERE RHR IRI REE REE EKER ERE ER ERR EERE REREREREEREKEEKEREREKE RE 


START: : LD SP, (0006) 7;SET STACK POINTER AT TOP OF MEMORY 
N.LINKIO LNKTB## ;SET UP IOS JUMP TABLE 
RRR AKER REK ER EERE REE REE ERE RE EEK EERE KEK REERE EE REREKE EERE REEREREREREREER 
3* THIS BLOCK OF CODE INITIALIZES THE VIDEO * 
7* CHIP REGISTERS, LOADS THE ASCII CHARACTER * 
;* SET AND SETS UP THE COLOUR TABLE FOR * 
7* WHITE LETTERS ON A BLUE BACKGROUND. * 
p RRR RRR AREER KERR EERE REE EERE KE REE KEKE KER EERE REE REE KER EKER EE EKEREEEREEREER 
CALL VSETG1 ;SET GRAPHIC1 MODE 
PCALL VPTRNST,0 7SET PATTERN TABLE ADDRESS 
PCALL VNAMEST,1C00H ;SET PATTERN NAME TABLE ADDRESS @ 


PCALL VATRIST,1FO0H ;SET SPRITE ATTRIBUTE TABLE ADDRESS 
PCALL VCOLRST, 2000H *SET COLOUR TABLE ADDRESS 
PCALL VSPRIST,3800H 7SET SPRITE GENERATOR TABLE ADDRESS 
SETCOLR DBLUE,WHITE +WHITE LETTERS ON BLUE BACKGRND 

g ARERR RERERERERERRE RRR EERE REE KRER ERR EIR IRR RI KEIR ERE IR ERIE EAI ERI EE 


7% DISABLE THE SOUND ON THE AUDIO REGISTER * 
RR RR RRR RRR R RARER KERR ERR EHR K KER ERE RIKKI IRE EERE EEE ERR REE EKER EERE 


PCALL AUDIOWR,7,3FH ?SET CONTROL REGISTER TO ZERO 
PCALL RPATRN, TCHAR 7LOAD ASCII SET 
PCALL VRAML8,20H,CLR1,2000H ;LOAD COLOR TABLE WHITE ON BLUE 


pRRRRRKRERK KEKE KEKE ERK EEE EEK EERE KR EERER ERK RER ERE REE EKER EERE RKRERERERERKEKRE 


3* THIS BLOCK OF CODE BLANKS THE SCREEN ® 


3* AND WRITES MESSAGES ON THE SCREEN. = 
g RRR RRR ERR RR RRR KEKE KERR EER RRR KEK KERR ERIK ERE RERRER EER EERE ERE REE HARE KERR 


PCALL VFILL,960,20H,1CO0H 7FILL VIDEO SCREEN WITH BLANKS 
CALL VBLKOFF 7TURN THE SCREEN ON 
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7PRINT MESSAGES TO SAY HELLO AND PROMPT FOR ESC KEY 


PCALL PUTMSG,MSG1 
PCALL PUTMSG, MSG2 
PCALL PUTMSG, MSG3 
PCALL PUTMSG, MSG4 


pERRRHRERAAKEK KEE KEREEEKERE KEE EERE ERE RE RE REE EER ER REKERREREREEERERRKEREERERERE 


:* THIS BLOCK POLLS FOR THE 'C' KEY BEFORE * 
;* CONTINUING. ENDD IS THEN ATTACHED TO THE * 
;* CLOCK ISR TO CHECK FOR 'ESC' KEY INDICATING * 
* END OF DEMO. * 
p RRR RAE KERR RKKEEEEEER EKER EE KER IK EEK KERR ERE EKER EKER EERE EREREREKEREEEEREEK 
LOOP: LD E,OFFH ;LOOP UNTIL THE 'C' REY-IS HIT 

LD C,6 

CALL 0005 

cP 'c! 

JP NZ, LOOP 


PCALL VFILL 960,20H,1C00H 

PCALL PUTMSG, MSG5 

PCALL VRAML8, 20H, CLR2,2000H ;LOAD COLOR TABLE BLACK ON GREEN 
SETCOLR MGREEN, BLACK 


LD HL, ENDD 
LD (ENDADR) , HL 
N.CLKAT TSKEND 


p ERR EERKE RE KE RKER EERE EKER EER EER ER EKER KERR RE RERE ERE KEKE RE KEE KEEREREEERE 


id THIS BLOCK INITIALLY SETS UP SPRITE PATTERN * 
ie AND INITIALLY PLACES A RED CIRCULAR SPRITE * 
7* ON THE SCREEN. * 


gp RRRREREREEK KEKE KER EERE KER KK EE REEERRE REE KEE RE EERERREREREREERERERERKEEEE 


?SET UP SPRITES 
PCALL LPATRN, SPRPAT,3800H ;LOAD SPRITE PATTERN 


PCALL SPNAME 0,0 7SPRITE 0,PATTERN 0 
PCALL SPMARK 1 7END OF SPRITE ATTRIBUTE 
LD A,6 7SET SPRITE TO RED 


LD (COLRR),A 

PCALL SPCOLR 0, (COLRR) 

LD A,O 

LD (OLDIR),A ;INITIALIZE OLDIR TO 0 
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LD A,30 @ 


LD (Y),A 

LD A, 40 7SET INITIAL SPRITE 

LD (X),A ;POSITION TO 40,30 

LD A,l 7TO PREVENT CONTINUOUS 

LD (XFLAG),A #SOUND WHILE TRAVELLING ALONG 

LD (YFLAG) ,A ;HORIZ AND VERT CENTERS, ENABLE 

+ FLAGS 

gE RRR R KEIR ERIK EH IKI RK RR EKER EIR KERIKERI ERE IRR RARE RIAA KER EEERREEEE 
7% THIS BLOCK ATTACHES SPRMOV TO THE CLOCK ISR TO HANDLE 7 
7* SPRITE MOVEMENT AND MAKING 'DING' 'DONG' SOUNDS bad 


PRR RREREKERKKEREE EERE REE EKER EERE ERE EERE REE EKERKEEEEKREKE REE REREREREREKREEE 


LD HL, SPRMOV 


LD (SPRADR) ,HL ;ATTACH SPRITE MOVE 
N.CLKAT TSKMSP #TO CLOCK 
INLOOP: JP INLOOP sINFINITE LOOP 


RERKERRKEKEEEKEKEKEREKREKE KE EEEKEKEEREERE EKER REE REE EERKEEREKEREEERREEEEEEREEEREEER 


ROUTINE NAME:SPRMOV @ 


me Ne Ne me Ne me 


FILE NAME: DEMO. MAC 

DESCRIPTION: USED TO DETERMINE THE NEW SPRITE POSITION, TO PRODUCE 
SOUND. THIS ROUTINE IS ATTACHED TO THE CLOCK. 

PARAMETERS PASSED: none 

PARAMETERS RETURNED: none 

REGISTERS CLOBBERED:REGISTER SAVED BY CLOCK 

GLOBALS ACCESSED: none 

GLOBALS WRITTEN: none 


COMMENTS and WARNINGS: 


Ne Ne Ne Se Se Ne te Me Se Se Me NO Se Ne Me Ne Ne Ne te te Se 
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GREER KEEE EERE EEK ERE KEE RERERERERER ERE EERE ERE KR REEREEERERERKEEEE 


7% THIS BLOCK OF CODE DETERMINES IF THE JOYSTICK * 
7* IS READY. IF DATA IS READY, THEN N.DEVIO . 
eal OBTAINS THE NEW DATA IN THE ACCUMULATOR. * 
4p RR EAERR ARE RRER ERR ERE ERE EEIREKE ERK EEE EKER ER EERE EEE KEREER ERE EEK HERREER 
SPRMOV: : 
LD A,l ?RESET FLAG 
LD (CPLAG),A 
N.DEVRDY 0,02 ;CHECK IF JOYSTICK HAS DATA 
JP NZ,CONT 7IF NEW DATA IS READY THEN GET IT 
LD A, (OLDIR) 7ELSE USE OLD DIRECTION 
JP MOV 
CONT: N.DEVIO 0,02 7GET NEW DATA 


LD (OLDIR) ,A ;SAVE THE NEW DIRECTION 


PERERA REEKEEREKRE EKER EERE HERE EERE REE EERERREER EKER EERE EREREKEREKEEEEREEER 


ad THIS BLOCK OF CODE DETERMINES WHAT THE NEW DIRECTION IS. * 
3* BITS ARE SET IN THE RETURN VALUE FROM N.DEVIO ACCORDING * 
3* TO WHAT THE JOYSTICK POSITION IS. * 
* * 
3* IF BIT 0 IS SET THEN MOVE LEFT * 
7* IF BIT 1 IS SET THEN MOVE DOWN * 
7* IF BIT 3 IS SET THEN MOVE RIGHT * 
7" IF BIT 4 IS SET THEN MOVE UP * 
3* IF BIT 5 IS SET THEN CHANGE THE SPRITE CLOUR AND PATTERN * 
DESIG IAI TOONS GGG CACO CC OITA IOT TTI I I I TAIT A 
MOV: SRA A ;SHIFT THE BITS TO THE RIGHT 

CALL C, LEFT ;AND CALL THE APPROPRIATE 

SRA A ROUTINE IF THE BIT IS SET 

CALL C,DOWN 

SRA A 

CALL C,RGHT 

SRA A 

CALL C,UPP 

SRA A 


CALL C , FIRE 
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PR RRRREEK ERE KEKERE EERE EKER EEK ER EREKE EKER EKER RE EER REE EEEREREEKEEREKEKEK 


:* THIS BLOCK OF CODE DETERMINES WHETHER THE SPRITE HAS CROSSED i 
3* THE VERTICAL LINE. IF IT HAS MAKE THE DONG SOUND. * 
PRR RRE RE RRR IRR REE ERR RE REE EEE RE REE REE IEI HIKER EEE RE ITAA IEERERERER IE 
LD A, (X) 7CHECK IF SPRITE CROSSES VERT LINE 
cP 115. 


JP NZ ,NOSNDX 7IF NOT THEN SKIP VERT SOUND 
LD A, (YFLAG) 


CP 0 7IS SPRITE STILL ON VERT LINE? 

JP Z,NOSNDX 7YES-SKIP VERT SOUND 

LD A,O 

LD (YFLAG) ,-A 7RESET FOR SOUND 

7PRODUCE SOUND FOR CROSSING VERICAL LINE 

PCALL AUDIOWR 0,120 7SET TONE 

PCALL AUDIOWR 7,62 7;ENABLE CHANNEL A 

PCALL AUDIOWR 8,31 ;MAXIMUM AMPLITUDE ,ENABLE ENV. 
PCALL AUDIOWR 12,56 #SET UP ENVELOPE 


PCALL AUDIOWR 13,0 


gH RER KE EA RHEE EERE ERK KERR ERE EERE RR EE EER ERE KE RERERERE EER KEREEREKREEER KERR 


7* THIS BLOCK OF CODE DETERMINES WHETHER THE SPRITE HAS CROSSED * 
:* THE HORIZONTAL LINE. IF IT HAS MAKE THE DING SOUND. * 
g BRERA ERE ERK KEKE REE EE ERE EER ERE EERE RE EEEER EER ERE KREEREEEEREREREERERE 
NOSNDX: ;CHECK FOR HORIZ. SOUND @ 

LD A, (Y) 

CP 90 ;CROSS HORIZ LINE? 

JP NZ,NOSND ;NO- THEN NO SOUND 

LD A, (XFLAG) 

CP 0 

JP Z,NOSND 

LD A,0 

LD (XFLAG) A ;SET FLAG 


?PRODUCE SOUND FOR CROSSING HORIZ. LINE 
PCALL AUDIOWR 0,32 +SELECT TONE 

PCALL AUDIOWR 7,62 7ENABLE CHANNEL A 
PCALL AUDIOWR 8,31 7;MAX. AMP. ENABLE ENV. 
PCALL AUDIOWR 12,56 ;SET UP ENVELOPE 
PCALL AUDIOWR 13,0 


NOSND: PCALL SPMOVE 0,(Y),(X) ;MOVE SPRITE ON SCREEN 
RET 


Sue ee ee vans @ 
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HIKER KIRK EERE EEE REE EE EE EE ERE EERE HEE EEEE EEE ERE REREEEREREEERERERER 


ROUTINE NAME:LEFT 


me Se Ne ne we 


FILE NAME: DEMO. MAC 


DESCRIPTION: UPDATES THE SPRITE POSITION 1 PIXEL TO THE LEFT 


PARAMETERS PASSED: none 
PARAMETERS RETURNED:none 
REGISTERS CLOBBERED:none 
GLOBALS ACCESSED: none 
GLOBALS WRITTEN: none 


COMMENTS and WARNINGS: 


Be Se Se Se we Ne te Ne te 88 Ne Ne Se te Se Ne Ne Se Se Ne 


LEFT: PUSH AF 7SAVE AF REGISTER 
LD A,l 
LD (YFLAG),A ;RESET FLAG FOR SOUND 
LD A, (X) 
DEC A ;UPDATE X POSTION 
LD (X),A 
JP NZ,LR 
LD A ,250 7IS SPRITE AT THE EDGE OF SCREEN 
LD (X),A 

LR: POP AF 

RET 
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ROUTINE NAME: DOWN 


a a en 


FILE NAME: DEMO.MAC 

DESCRIPTION: MOVES THE SPRITE'S POSITION 1 PIXEL DOWN 
PARAMETERS PASSED: none 

PARAMETERS RETURNED: none 

REGISTERS CLOBBERED:none 

GLOBALS ACCESSED: none 

GLOBALS WRITTEN: none 


COMMENTS and WARNINGS: 


we Ne Se Se Se te te Ne Se Se Se Se Ne Se Se Se Ne Se te 


DOWN: PUSH AF 
LD A,l @ 
LD (XFLAG),A 
LD A, (Y) 
INC A 
LD (Y),A 
CP 180 
JP NZ ,RD 
LD A ,0 
LD (Y),A 
RD: POP AF 
RET 


RGHT: PUSH AF 
LD A,l 
LD (YFLAG),A 
LD A, (X) 
INC A 
LD (X),A 
CP 245 
JP NZ ,RR 
LD A ,0 
LD (X),A 

RR: POP AF 
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ROUTINE NAME: UPP 
FILE NAME: DEMO.MAC 


DESCRIPTION: MOVES THE SPRITE ONE PIXEL UP 


PARAMETERS PASSED: none 
PARAMETERS RETURNED:none 
REGISTERS CLOBBERED:none 
GLOBALS ACCESSED: none 
GLOBALS WRITTEN: none 


COMMENTS and WARNINGS: 


Be Se Ne Ne Se te MO Te Ne Ne Se Se Ne Ne Me Ne Se Me Se Ne 


() 


UPP: PUSH AF 
LD A,l 
LD (XFLAG) ,A 
LD A, (Y) 
DEC A 
LD (Y),A 
JP NZ,UR 
LD A,180 
LD (Y),A 

UR: POP AF 
RET 


RAKRREKREKREEEKKEEEKEKEREKEEEKEEEREREEEEEEEKEEREEEREREEKREEREREEEERKREREREKEKERKKEEKKE 


a 
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ROUTINE NAME: FIRE 


te Ne Ne Se Se 


FILE NAME: DEMO.MAC 
DESCRIPTION: WHEN FIRE BUTTON IS DEPRESSED, A RED CIRCLULAR 
SPRITE IS TOGGLED TO A BLUE SQUARE OR BACK AGAIN. 

PARAMETERS PASSED: none 

PARAMETERS RETURNED:none 

REGISTERS CLOBBERED:none 

GLOBALS ACCESSED: none 

GLOBALS WRITTEN: none 


COMMENTS and WARNINGS: 


mB NB Ne Ne Se Ne we Ne Sc Se Ne Se Ne we Ne Se Se Ne Se Se Ne 


FIRE: PUSH AF 
LD A, (CFLAG) 


CP 0 7;HAS SPRITE BEEN CHANGED RECENTLY 
JP Z,FIRER +YES ~THEN RETURN 

LD A,0 

LD (CFLAG),A ;RESET FLAG 

LD A , (COLRR) 

CP 7 71S IT RED 

JP Z ,REDD ;YES- CHANGE SPRITE TO A SQUARE 
INC A 


LD (COLRR),A 
PCALL SPCOLR 0,(COLRR) ;AND CHANGE THE COLOUR 


PCALL SPNAME 0,5 ;MAKE IT A CIRCLE 
JP FIRER 7GOTO RETURN 

REDD; PCALL SPCOLR 1,(COLRR) ;CHANGE COLOUR TO BLUE 
DEC A 


LD (COLRR),A 

PCALL SPCOLR 0,(COLRR) ;CHANGE IT TO BLUE 

PCALL SPNAME 0,1 7MAKE THE SPRITE A SQUARE 
FIRER: POP AF 

RET 
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ROUTINE NAME: ENDD 


we me we te te 


FILE NAME: DEMO. MAC 
DESCRIPTION: DETERMINES WHETHER THE ESC HAS BEEN DEPRESSED 
AND IF IT HAS REBOOT THE SYSTEM. 

PARAMETERS PASSED: none 

PARAMETERS RETURNED:none 

REGISTERS CLOBBERED:none 

GLOBALS ACCESSED: none 

GLOBALS WRITTEN: none 


COMMENTS and WARNINGS: 


me Se Se Ne Se Ne Ne Ne Se Me Ne Ne NO Ne Ne Se Ne Se Se MO Ne 


7POLL FOR ESCAPE KEY 
ENDD: PUSH AF 


N.DEVRDY 0,01 3IS THE KEYBOARD READY 
cP 0 
JP Z,NOEND 7YES-THEN GET DATA ELSE RETURN 
N.DEVIO 0,01 ;GET DATA 
CP 1BH 7IS IT THE ESC KEY 
JP NZ ,NOEND 7NO -RETURN 
LD C,0 7YES REBOOT CPM 
JP 0 
NOEND: POP AF 
RET 
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PERERA KERAE ERE EERE REE KEKE ERE KERR EEK EKER ERE EE ERE EEE EKREERE EER ERERER © 


;* THIS IS THE DATA FOR THE COLOUR TABLE * 
pRRRR RAR KERERKEEE RK ER EKERERKEE ERE RRR REE REER EER EKEEE EEK ERE REREEKEREEEEEERERE 


«RADIX 16 
CLRI1: DB OF4,0F4,0F4,0F4,0F4,0F4,0F4,0F4 
DB OF4,0F4,0F4,0F4,0F4,0F4,0F4,0F4 
DB OF4,0F4,0F4,0F4,0F4,0F4,0F4,0F4 
DB OF4,0F4,0F4,0F4,0F4,0F4,0F4,0F4 


CLR2: 
DB 012,012,012,012,012,012,012,012 
DB 012,012,012,012,012,012,012,012 ;COLOR TABLE ENTRIES 
DB 012,012,012,012,012,012,012,012 
DB 012,012,012,012,012,012,012,012 
END 


KRRRKEKEKEREREREEKRE REE EE KERR REE EE EKREKREKREKREKRERERREREEREEEEKEKKEKE 


The SPRPAT.MAC file 
RE REK KEKE EERE KR ER ERK KEERKER ERK KKK RE KKK EEE EREKKEEKRERERERERRERES 


me me Ne 


-Z80 

CSEG 

»RADIX 2 
@ 
; 
SPRPAT: : 


DB 008H 


se se 


DB 000H,000H,001H,00FH,01FH,03FH,03FH,07FH,07FH 
DB 001H,07FH,03FH,03FH,01FH,COFH,003H,001H,000H 
DB 002H,000H,080H,0C0OH,OFOH,OF8H,0FCH,0FCH,OFEH 
DB 003H,0FEH,OFCH,OFCH,OF8H,0FOH,0COH,080H,000H 
DB 004H,OFFH,080H,080H,080H,080H,080H,080H,080H 
DB 005H,080H,080H,080H,080H,080H,080H,080H,0FFH 
DB 006H,OFFH,001H,001H,001H,001H,001H,001H,001H 
DB 007H,001H,001H,001H,001H,001H,001H,001H, 0FFH 


ot 


END 


=e 
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RREREKEKEKEKEEKEEKEEEKEKIKIK EE EREREERER KERR EEK RERE RE EREREREREREEKEKEKREEEKEEKREE 


ROUTINE NAME: LNKTB 
FILE NAME: LINKTAB.MHO 
DESCRIPTION: 


LNKTB is a driver table used by the application to establish 
user access to IOS routines. The table must exist if 

any of the IOS routines are to be used. Before the routines 
may be accessed, the table must be initialized. 


The table consists of all the IOS routines associated with 
VDP, windows and cursors, and attaching tasks to the 

clock interrupt. To use the table, delete any entries which 
are not called by your software. This leaves only the 
routines accessed by your code. 


After the unused entries are deleted, the table must be 
assembled and the assembled version included in the 
final link of the application. 


AUTHOR: Trevor Pearce 

DATE and ISSUE: August 4, 1982 Version 1.0 

CATALOGUE ID: HCF - AS - 0051 

PARAMETERS PASSED: none 

PARAMETERS RETURNED: none 

REGISTERS CLOBBERED: none 

GLOBALS ACCESSED: all VIDEO, SCREEN and CURE entry points 

GLOBALS WRITTEN: all accessed globals are written during 
initialization 

COMMENTS and WARNINGS: 
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-Z80 
-RADIX 10 
LNKTB:: 
DB (TABEND-TABSTRT) /3 ; Do not delete this line 
? 
TABSTRT: 7 Do not delete this line 
REGRD: : 
VREGRD:: DB 00H,0,0 
VTABR: : 
VTABRD: : DB 01H,0,0 
? 
CRBEG:: DB 02H,0,0 
? 
CREND: : DB 03H,0,0 
; 
REGWR:: 
VREGWR: : DB 04H,0,0 
STATR: 
VSTATRD:: DB 05H,0,0 
3 
NAMST: : 
VNAMEST: : DB 06H,0,0 
7 
COLST: : @ 
VCOLRST: : DB 07H,0,0 
PTRST: : 
VPTRNST:: DB 08H,0,0 
7 
ATRST: : 
VATRIST: : DB 09H,0,0 
? 
SPRST: : 
VSPRIST: : DB OAH,0,0 
; 
BLKON: : 
VBLKON: : DB OBH,0,0 


, 


eecceeee CCC. etc. etc. 


; 
TABEND: ; Do not delete this line 


END 


Spec. 50~-90020490 Page 9 - 21 


June 8, 1984 


